The package javadoc for javax.management.namespace is the likely starting point for most developers discovering this new feature. Although it contains all the necessary information, the organization could be improved. It should start by showing what a system with namespaces looks like, with the foo//bar syntax immediately, and some use cases. Only then should it get into the details of how to set up namespaces.