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

 >>  2. Help the documentation team move forward by improving (a) Drupal's
 >>built-in help system and (b) book module.  The latter includes (1)
 >>better integration of non-book pages in the book module (Nick Berendsen
 >>has been working on this) and (2) a better review/workflow model to
 >>facilitate the acceptance of updates.
 >
 > Frankly, I haven't put much effort in the book module because I 
believe we
 > should maintain the Drupal documentation using LaTeX or Docbook but that
 > is another story.
 >

Just thinking that Drupal should eat it's own dog food here. If the book 
module is (or to be) an effective collaborative authoring tool, then 
wouldn't it make more sense to expand it's capabilities?  Make it more 
suitable for producing the documentation and make it easier to integrate 
into the help system.

I can understand how LaTeX or Docbook might make a better immediate 
solution in terms of

(a) control of formatting
(b) use by the core developers.

But it would seem to do so at the expense of

(c) larger community interaction in developing documentation (for 
example, many other users are not comfortable with Docbook or LaTeX or 
the process of checking in and out of CVS; keeping it in CVS doesn't 
make it very accessible either).
(d) further development of the book module (case in point, Dries's 
comment above).

Also, if this line of thinking had been followed in terms of project 
development, then would it have made any sense for Drupal developers to 
have done a major revision to the project module? Seems as if it have 
been easier to have adopted another project solution instead.

Maybe this is just me because I see great potential in the book module, 
instead of just as a display mechanism for documentation.

And maybe because I know that it would be easier for me to participate 
in documentation writing *if* it was possible to contribute via the 
handbook on drupal.org. Right now, because of problems with the module, 
workflow difficulties with getting documentation from drupal.org into 
the help system, and the fact that much of the documentation used by the 
help module is not actually stored in the node table on drupal.org, 
contributing is a difficult, discouraging process. For instance, there 
are still some updates I wrote for 4.2 a few months ago that are on site 
which never made it into 4.3rc for some of these very reasons.

Charlie Lowe
http://cyberdash.com/

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