Drupal comments on Drupal

Kristof Van Tomme said of Drupal:

"The biggest strength of Drupal as a documentation solution for an open source project is that Drupal has community written all over it: your users can log in, edit, flag, tag, comment, rate and with the revision system Drupal can become much like a wiki but with forms you can design yourself."

"Our current biggest weaknesses in Drupal as a documentation tool are in my opinion: Lack of a good way to deal with differences in documentation between versions (currently we just duplicate all of our docs when there is a new release of Drupal core) and the
proliferation of documentation topic formats (e.g. sometimes individual topics get their own page, sometimes multiple are grouped in 1 page, etc.). These weaknesses could be addressed with a single sourcing content standard such as DITA."

"Probably you'll be interested in the work we've been doing on a module that would make it possible to work with DITA, an OASIS open standard for single sourced documentation in Drupal. We have a first development release of the module over at http://drupal.org/project/dita"

Regarding auto-generated API docs:

"As you can see our API docs can have comments, and through that somewhat allow for more narrative content. But besides of this and of some content references to the API docs from the Drupal documentation there is no real integration. In DITA API docs would be reference type topics, that could be included in a DITA map and through a relationship table cross-referenced from the more narative documentation (tasks and concepts)."

Jennifer Hodgdon said of auto-generation and versioning:

"The API module is used to generate api.drupal.org, which is the reference site generated from code comments. It's not integrated particularly into the rest of the on-line documentation."

"All of our on-line documentation (drupal.org/documentation) and our in-code documentation is written with community input – we're a big open-source project. Pretty much anyone can edit most of the on-line docs. The in-code doc goes through the same patch review process as code changes."

"The API reference in-line doc is updated with the code (at least in principle, not always in practice but it tends to be pretty up-to-date). So it's automatically synchronized with Drupal versions. We dont' really have a good system for versioning in the on-line documentation at this time. That's an issue we're wrestling with."