diff --git a/README.md b/README.md
index 1a608b7..b782b5a 100644
--- a/README.md
+++ b/README.md
@@ -7,4 +7,11 @@
 * always initialize all members. Better safe than sorry.
 * Ownership of the member pointees: rule of thumb: "const" pointees are non-owned, non-const pointees are owned by the data structure. Exceptional cases are documented explicitly.
 
-## API
\ No newline at end of file
+## Public API
+* defined in `namespace pEp` – Beware: it is shared with libpEpAdapter!)
+* header files are installed in `PREFIX/include/pEp/` and are used via `#include <pEp/filename.hh>` – (Also shared with libpEpAdapter!)
+* the linked list datatypes implement the API of [`std::forward_list`](https://en.cppreference.com/w/cpp/container/forward_list)
+
+## Implementation details
+* internal stuff is in `namespace pEp::datatypes`
+