Thanks for the clarification guys. The only thing that I havea little concern over is the bit about hierarchical presentation of the API. If you mean segmenting application types as in web api and native then that fine. Within each type of application though the API needs to be based on subsystem divisions inline with framework, if not the documentation will be ignored by the devs I have spoken too and another set painstaking constructed for ourselves as this is the way we expect to find information.

Regarding best practice it might be worth adding some coding standards to cover style and naming if not already considered then following that through with sections from the example programmes to highlight.