diff --git a/docs/attributes.rst b/docs/attributes.rst
index 39973659cf5fed577901d6e016c1e66add991740..018fe8abd90769c9da66ce88a8b5ace8fbd024e3 100644
--- a/docs/attributes.rst
+++ b/docs/attributes.rst
@@ -1,7 +1,38 @@
 Attributes
 ==========
 
-TODO
+:class:`polymesh::Mesh` stores pure topology, no positions, no normals, no other attributes.
+All data associated with mesh primitives are stored in so-called external attributes.
+
+Motivating example: ::
+
+    // create empty mesh
+    pm::Mesh m;
+
+    // create position as external vertex attribute
+    auto pos = pm::vertex_attribute<tg::pos3>(m);
+
+    // create a vertex (pos is automatically resized as well)
+    auto v = m.vertices().add();
+
+    // assign position
+    pos[v] = {1, 2, 3};
+
+    // compute face normals (functional style)
+    auto f_normals = m.faces().map([&](pm::face_handle f) { return pm::face_normal(f, pos); };
+
+    // compute vertex normals (imperative style)
+    auto v_normals = m.vertices().make_attribute<tg::vec3>();
+    for (auto v : m.vertices())
+    {
+        auto n = v.faces().sum(f_normals);
+        v_normals[v] = normalize(n);
+    }
+
+
+External Attributes
+-------------------
+
 
 Integrating Mesh and Attributes
 -------------------------------
diff --git a/docs/mesh-topology.rst b/docs/mesh-topology.rst
index ea7224c7ca8139a1187d9f28bc1238490369cb9f..3b7d06011f04e7bbec197bb18207adbcc602e513 100644
--- a/docs/mesh-topology.rst
+++ b/docs/mesh-topology.rst
@@ -1,6 +1,29 @@
 Mesh and Topology
 =================
 
+Motivating example: ::
+
+    // creates an empty mesh
+    pm::Mesh m;
+
+    // add some vertices
+    pm::vertex_handle v0 = m.vertices().add();
+    pm::vertex_handle v1 = m.vertices().add();
+    pm::vertex_handle v2 = m.vertices().add();
+
+    // add a face
+    pm::face_handle f = m.faces().add(v0, v1, v2);
+
+    // iterate over edges
+    for (pm::edges_handle e : m.edge())
+        std::cout << "v" << int(e.vertexA()) << " -> v" << int(e.vertexB()) << std::endl;
+
+    // split face
+    pm::vertex_handle v = m.faces().split(f);
+
+    // navigate the mesh
+    v = v.any_outgoing_halfedge().next().vertex_to();
+
 
 Mesh Class
 -------------