Documentation, Module Maintainers, Documentation Maintainers, and Documentation Templates

I would like to attempt to use this thread for brainstorming some process improvements for documentation, specifically contributed module documentation. I will try and moderate the discussion by keeping running lists of what's said, asking for consensus or general agreement, and then submit the results as a documentation issue request for final approval. This thread was inspired by another discussion at: http://drupal.org/node/141090. I apologize in advance if all of this has been discussed before and was found to be unwanted.

This is not intended to be a hop on gripe fest. I think everyone is aware that the documentation could use some improvement, however I would like to personally say that I think those who have been documenting thus far have doing a remarkable job. Like I said before, I would like to focus on contributed module documentation.

I has been said in many places by many module maintainers that they just aren't interested in documentation. This is fine, there are many "documenters" who are. There are also many "mental" obstacles to just picking up and documenting someone else's work.

Being able to write documentation is not just and exercise in taking notes of the steps to install something or how you accomplished one specific task using a module. Writing good documentation requires knowing not just about the module, but what the developer's intentions are in writing the module. It requires a special kind of insight that can most easily comes from having written the code oneself, or by having a direct line of communication with the module maintainer.

This is why I would like to suggest having document maintainers along with module maintainers, listed right alongside on the module's project page. Implementing this would require making some changes in the various "contributing to documentation" pages to make people aware of this cultural "requirement". You would probably want to put notes somewhere in the info for new module maintainers that they should seek out a documentation maintainer. Perhaps we could establish a document maintainer's queue? A Drupal classified space for coders seeking documenters? I'll let others hash this out a bit.

The other thing I would like to discuss in relation to documentation is a standard template or format for documenting modules. I realize that it needn't be strictly adhered to, but it could act as a good guideline for new documenters who would like to document a module, but don't know where to start. Here is my baseline suggestion for a template:

1) Front Page - (Preferrably straight out of the README.txt)
a - Intro
b - Rationale (Why use it, feature comparison to other Drupal functions)
c - Prerequisites (Other modules that need be installed first, plugins, addins)
d - Coming Soon section (Requested write-ups from the comments section)
2) Child - Installation (Preferrably straight out of the INSTALL.txt)
3) Child - Admin pages explained
4) Child - Special permissions explained
5) Child - Listing of installed modules and submodules and functions
6) Child - Table structure
7) Child - FAQ (Drawn from the module's issue queue and from comments.)
8) Child - REAL EXAMPLES (Things people have done with the module, sites using it?)

There are a couple others that I think I like but I'm not so solid on.

1) Child - Actual code from each file in the module directory. Each file gets a child page of this page. (I know this could get ridiculous for some modules) The nice thing about this in my opinion is that the code gets indexed by the search engine.
2) Child - Advanced user section.

Now keep in mind, not all of these sections need to be filled out at once. Maybe someone only will feel like filling out the installation page. But, I feel that if you add all of these bones for an outline, it's like giving people lines to color in. And that's more what documentation is about. It's not really creative free flow train of thought off the cuff writing. It's an attempt to give a standardized experience with often times not so standard applications. It's about the how, why, where, etc.

Also keep in mind, that part of the existing "duties" of the documentation team is in fact to review comments and incorporate them into the handbook pages if warranted. It's not much further of a step for a specific doc maintainer for a module to also view the issue queue and pull out FAQ's. Anyhow, enough blabber from me. Please chime in and say what you think.

Thanks,
Jonathan
http://www.kfol.org/