User login

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

Searched words: 
documenting a site with advanced help Drupal

Comments

Great idea

This is a really noble concept. I usually include a style guide with the sites I build, but it's just a separate html and css file. It would be great to be able to include that within drupal, as well as a basic guide to operating the sites and possible FAQs.

Post new comment

The content of this field is kept private and will not be shown publicly.
  • You may post code using <code>...</code> (generic) or <?php ... ?> (highlighted PHP) tags.
  • You can use Markdown syntax to format and style the text. Also see Markdown Extra for tables, footnotes, and more.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <img> <blockquote> <small> <h2> <h3> <h4> <h5> <h6> <sub> <sup> <p> <br> <strike> <table> <tr> <td> <thead> <th> <tbody> <tt> <output>
  • Syntax highlight code surrounded by the {syntaxhighlighter SPEC}...{/syntaxhighlighter} tags, where SPEC is a Syntaxhighlighter options string or "class="OPTIONS" title="the title".
  • Lines and paragraphs break automatically.

More information about formatting options

By submitting this form, you accept the Mollom privacy policy.