Re: Re: [drupal-devel] documentation and the book module (was reflections on the Drupal 4.3.0 battle)

Dries Buytaert wrote:
> On Wed, 22 Oct 2003, Charlie Lowe wrote:
> 
>>>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.
> 
> 
> Making the book module suitable involves versioning and workflow that
> supports branches: we should be able to retrieve an old version of a book
> (not just a page) as well as maintain specific versions.
> 
> I have been approached by a publisher that wishes to publish the Drupal
> handbook.  The current handbook is not suitable because (i) the format is
> not suitable for print, (ii) the book lacks consistency (writing style,
> mark-up) and is not (iii) well-balanced.  Also, we have no means to
> generate an index and to do other book-like things.

First, I never thought it was trivial to modify the book module to be 
more effective :)

Second, what concerns me is that you are suggesting more of a 
programmer-friendly method of documentation writing and versioning 
rather than a writer/community-friendly one. Formatting for markup and 
creating indices are, in my mind, trivial when compared to content 
creation and editing for consistency in style. Give me the handbook for 
a weekend as it stands right now, and I think I can put it in a 
publisher ready markup format. Then we could develop the index from 
there. And that only needs to be done once every so often for the 
publisher (maybe once every few years). But editing the handbook for 
consistency, expanding on content (some areas of the administration 
guide are in need of more user-friently, detailed information) is a lot 
more work then that and an ongoing project that will continue throughout 
versions of Drupal.

So why not, then, devote serious attention to figuring out how to make 
Drupal a more powerful publishing engine, rather than simmply abandoning 
Drupal as the platform for producing it's own documentation? Isn't that 
worth consideration first?

 >
 > I believe none of the above is going to happen unless we move the
 > documentation to CVS and maintain it like we do with the code.  I'm
 > confident that the result will be a better manual.
 >

Certainly, if it gets the developers motivated to work on the manual. 
But it will discourage myself and others who are not comfortable with 
CVS and don't find it a particularly well-suited collaborative writing 
environment. What happens if developers are no more motivated as they 
are now after you make the change?


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