[drupal-docs] Handbook v2

[Dries Buytaert]

>> I wonder though,how we might exploit this model to better serve
>> maintaining documentation for multiple versions of Drupal or better
>> keeping docs consistent with HEAD?
>
> Kind of like "tagging" a version. Versioning is the big issue we have 
> to deal with that I really have no idea how to address other than with 
> extra functionality of books. I also don't think we're ready to tackle 
> versioning quite yet, but that in moving forward we should have some 
> ideas how to handle it.

Sigh.  :)

In October 2003 (!) I predicted that no significant improvements would 
be submitted for the book.module and that this would have negative 
impact on our documentation.  See 
http://lists.drupal.org/archives/drupal-user/2003-10/msg00053.html. I 
said: "If you don't believe me, fine, I'll sit back, wait and see.  
Prove me wrong.".  So far that didn't happen.

For more than two years now I've been advocating the use of 
"professional documentation writing tools" (LaTeX or Docbook) combined 
with version management (CVS) to produce documentation.  The 
advantages:

   1. Tracking changes would be a non-issue.
   2. Having different versions of the handbook would be a non-issue.
   2. Having a review process would be a non-issue.
   4. Consistent markup/formatting would be a non-issue.
   5. Exporting the documentation in various formats would be a 
non-issue.
   6. Editing the documentation would be a lot easier (spell-checking, 
search-and-replace, cut-and-paste).

Conclusion: it solves all pressing problems.   Thinking that items 1 to 
6 will get fixed in the near future is a strategic mistake.  Wake up.  
We've been discussing that for two years now.  Unless someone invests x 
months of development in this, it won't happen.

- I bet that if we had switched to LaTeX/Docbook+CVS in October 2003, 
we would be able to send a copy of the current documentation to a 
publisher and have it published with little effort.  Fortunately, we do 
maintain most of the API documentation in CVS, which has been a 
success.  I've heared few complaints about the quality of that.

I just wanted to share my opinion hoping we don't make another 
strategic mistake.  Regardless, I'd be happy to give you guys another 
wildcard, to setup more root books, to install the notification module 
or whatever code gets written.  Other than that, I'll sit back, wait 
and see.  Simply because I think it won't work.

--
Dries Buytaert  ::  http://www.buytaert.net/