Re: documentation and the book module (was reflections on the Drupal 4.3.0 battle)

I've been following the various discussions on documentation and have
had some discussions on the side with various people as well, but
honestly I don't know much about DOCBOOK or LaTeX to comment on how they
can be used.

What I have noticed is that the needs haven't really been discussed,
people seem to have jumped to solutions.

Currently Drupal is documented in part in the source code and in part in
the book module on drupal.org. This presents a few challenges as to
update the documentation you have to figure out where it is stored. If
it is in the book you can update it, but then it has to be approved by
someone who has access to do so. If it is in the source code someone
needs to submit a patch and commit it. This presents a maintenance and
administration problem -- hard to update and hard to see what changes
have been made and approve them, and occasionally something gets lost or
forgotten.

Another problem is that Drupal is a moving target. The documentation for
Drupal 4.3.0 won't be the same as the documentation for 5.0.0. This
makes it hard for the end users to find the proper documentation for
the release they are currently using, and causes problems between
releases as the book becomes updated some sections are irrelevant for
the current release, but apply to a future release.

We should also have a set of formatting and style standard so all pages
look the same.

What I think we need is:
  * A way to bring all the documentation into one place so it can be
    edited independently of source code or anything else. This of course
    means that Drupal somehow has to be able to access the documentation
    for the help.module, or we have to give up on combining them and
    maintain them separate.

  * Support for several versions of the documentation for each of the
    Drupal releases.

  * Transparent updating that can be reviewed by the community, either
    before it is included or afterwards (requires revision control of
    some kind).

  * A consistent form of structure and styling.

  * Editable in some form by people who are not necessarily technical in
    nature.

Some of this introduces new challenges. If we take the documentation out
of the Drupal source then we also need to do that for contributed
modules, so we need a way that they can include documentation or support
both external and internal help.

No matter what solution we end up with it results in a need for some
development. If we use the book module then it needs to be extended to
support branches and enforce structure, we also need some way to bring
the documentation back into Drupal for the internal help.

Using DOCBOOK or LaTaX with CVS greatly increases the bar for users to
create documentation as there doesn't seem to be any easy to use tools
available, but I could be wrong about that.

We can combine the two in some form where the documentation is stored in
a DOCBOOK format in CVS, but we have a module on drupal.org that lets
you edit the page online (and send a diff to the -user list for someone
technical to apply it?).

Or maybe there is some other alternative that hasn't come up yet.

-- 
Kjartan <[email protected]>
:: "Smash forehead on keyboard to continue."

-- 
[ Drupal user list | http://list.drupal.org/ ]
[ http://lists.drupal.org/options/drupal-user/gcpdu-drupal-user%40gmane.org ]