improving doc

docs/attributes.rst

 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
 -------------------------------

docs/mesh-topology.rst

 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
 -------------