Documenting a Drupal site using the Advanced Help module

In the Agaric annual brainstorm, it occurred to me that the Advanced Help module could also be used for site-specific documentation— both for users and developers.

Documentation is not something you want to trust to the vagaries of the often unstable content of a site in development, but at the same time you would rather have configuration and use information embedded in the site than in a separate document of which everyone needs to keep track.

Advanced Help module provides documentation for Views and other modules supporting its integration, and it stores this help text in HTML files. We can further used it to document the development and use of an SCF, or any complex, site.

This puts the "how to configure" and "how to use" information right in version control with the rest of the site's code. While code can and should be commented in the PHP files themselves, this isn't such a great location for configuration notes. It is especially not a good place for administrator-facing configuration information. Code comments are right out for end user explanations!

Advanced Help lets this code be committed to the revision control / source code management system handling the rest of the site, yet displayed in the user interface in a consistent way.

In responding to a feature request for using Advanced Help for different kinds of documentation, merlinofchaos makes clear that his module can be used to put help most anywhere (with form_alter, which happens to be my favorite Drupal hook anyway).

While Advanced Help does not allow for permissions to give user roles different leves of access, developer and configuration documentation (work which should not be done directly on a live site in any case), user and administrator documentation can go in one module (enabled on the live site) and developer and configurer (configurator?) documentation can go in another module which should not be enabled on the live (also known as production) site.

Resolution