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

Kjartan Mannes wrote:
> 
> 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).


I seem to remeber that someone suggested that the next upgrade to the 
help system might include storing help as HTML files. Assuming this were 
the case, consider

1) Documentation development for CVS version is done on drupal.org in 
the book.module. Older versions would occur by updating the HTML files 
in the CVS repository. This allows the larger community to be involved 
in the main documentation creation and updating.

2) Each documentation page needs a unique identifier. Could just use the 
identifiers generated by the node. Drupal.org would need a table of 
those identifiers and their corresponding file in CVS. Each night, 
before CVS nightly tarballs are created, Drupal would need a script to 
diff the HTML files stored in CVS with book module pages.

3) When a new module is added to contrib and documentation work is begun 
on site in the book module, the table of identifiers on drupal.org would 
have to be updated manually. A drawback, but this probably should not 
happen too often. And a whole lot simpler than the current system of 
building a page on the book module, then updating the code in CVS within 
the module file.

4) Translations into other languages of documentation can be done in CVS 
with the HTML files (note also that HTML versions of documentation also 
makes it very easy for anyone to customize their documentation for their 
individual drupal site).

5) I've seen a Docbook HTML conversion tool. Seems as if these HTML 
files could be converted to Docbook, then a style sheet applied, for 
doing fancy pdf work or producing the print publication Dries mentioned.


> 
>   * A consistent form of structure and styling.

This is the hard part no matter which way you go. In my experience, 
publishers and other projects with many writers require the use of an 
editorial style sheet. However, even with qualified, dedicated writers, 
an editor(s) still has to go behind the writers and create more 
consistency to make someting of publishable quality.

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

Thus the use of the book module, for the greater work on the 
documentation, and HTML, for permanent storage and versioning. HTML is 
about the most standard mark up language you are going to find that is 
familiar to all of the Drupal community.

Then let those doing specialized projects with the documentation convert 
HTML to the markup language of their choice, just as I did with the 
sample pdf I posted yesterday. After all, the differences between the 
pdf I put up and the original book module output are just another style 
sheet used by the particular tool that I like. With HTML as the base 
mark up for documentation, anyone else can do the same, whether it be 
with Docbook, an XML editor, Dreamweaver, Microsoft Office, whatever.

Charlie Lowe

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