Six Reasons To Get A Handbook Page For Your Module
Checkout view being currently disabled in ViewVC is a very good opportunity to remind everyone that linking to your README.txt file in CVS does not count as documentation on your project page!
Here are some things I, or anyone else, can do with a proper documentation page in what used to be called the handbooks section of drupal.org:
- Correct it.
- Expand on it.
- Clarify things for newbies.
- Add a section listing modules that works with yours that users might be interested to know about, thus helping a tiny tiny bit to make sense of the Big Lego Box.
- Share some of the things I've done to theme your module.
- Add to a section on troubleshooting, and hopefully keep some of the more recurring issues out of your queue (or at least give you somewhere to point to in slightly self-righteous manner ;)
In short, with a little bit of seeding (some basic explanations of the concepts of your module and some instructions), you open it up to a whole community of potential writers and editors. Which is a concept we should all be familiar with!
If you say that keeping a documentation book page in sync with your CVS readme file is too much of a hassle (and who said it should be in sync anyway?) then it's because you've not thought about the benefits.
I prefer just the normal
I prefer just the normal homepage. Why get a handbook page when you can use the right column plug?
I wanted to note that there's
I wanted to note that there's an issue in the doc queue (http://drupal.org/node/617162) to dramatically overhaul the information architecture of the current Getting Started and Beyond the Basics books. This would very much impact the module documentation as all content (whether it's for core or contrib modules) would be relocated to the most appropriate context (as opposed to what we have now, which is basically just a massive jumble of unrelated stuff)
For example, there are some modules like which are specifically of interest to developers. They would be moved to the developing guide. If a module is mostly used for theming, the documentation would go to the theming guide. If a module is relevant to both developers and themers, there would have to be a judgement call about where to place it, but there would be at least a cross-reference from one guide to the other (eventually we'll reach a point where the same content could display in two places but exist as one source in the database)
Post new comment