We all know that our Drupal issue external documentation technique is untenable.
We do internal documentation (the Doxygen comments that are included in the code and result in api.drupal.org) pretty well now in Drupal 7 (Yay!). Documentation of functions and hooks is done in the patch itself and gets reviewed and improved in the process of the patch's development. Drupal 7's internal documentation is incredibly improved over previous versions. Drupal++.
However, our external API and usage documentation and API change documentation (the handbook and related resources that give a big-picture idea of APIs and how to use Drupal) has a long way to go, because it's been treated as a second-class citizen.
Here's what we (mostly) currently do: Work and work on an issue. Come to a community consensus on the patch. After great pain, finally get it committed. Then (maybe) mark it as "needs documentation". Now that's really treating something as second class. Documentation needs to be first class in the development process, as it's critical to our future. If people don't know how to use Drupal well, Drupal will be far less successful.
Here are some simple changes that would improve this process:
- Require and prepare the documentation that goes with an issue *before* it gets committed. I know that it's too much of a pain to do the documentation before the patch is ready, but here's a proposal:
- Add a new issue state, called "committable" or some such, which means that the committer has signed off on it and will commit when requisite documentation (or other dependencies) are fulfilled.
- When the issue has reached "committable", docs can be prepared. They can be prepared right in the issue, or in some other appropriate spot. Since the signoff has already been achieved, upgrade notes could already be done on the update page. They could also be done in the handbook, if they belong there.
- Of course some code developers are not comfortable with writing. So we have to enlist people in the queue to do the docs. We do this in many specialized areas of code development, so why not here too?
- Explicitly handle API change documentation as a part of the development process. See Document API changes as a part of the development process
Here's my overall rant on improving the issue queue which I'll rant on for anybody who will listen.