[drupal-docs] Handbook v2

[Gabor Hojtsy]

> 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.

You are right in some sense. I am also a big fan of ready to use version 
control systems, but human problems arise if we use some non-HTML format 
in CVS. People need to have ready to use tools on their desktop to make 
things work. A build system to check for validity errors before 
submitting, etc. From experience I would say that having to see the 
document written in some enduser format is a requirement for some. They 
are basically not capable of imagining what is going to end up on the 
screen from some source text. This was one of the reasons that some PHP 
guys started to develop Livedocs [1] for the PHP documentation, which 
still needs a small build system, but then allows one to quickly review 
changes in HTML. It is not complete, and not general enough yet, but it 
is supposed to serve the PHP documentation on the hundreds of the mirror 
sites in the future. BTW the PHP docs use DocBook XML.

[1] http://wiki.phpdoc.info/LiveDocs

Goba (editor of the PHP Documentation)