Misc docs suggestions

I'd say you should mention that the semantics do NOT depend on the naming scheme.