[drupal-docs] Handbook v2

[Anisa]

I feel really tempted to say that problems with development of core 
modules should go on the devel list.  ^.^  But see, I repress my 
inclination to be facetious. ;)

So the doc team works with the book module they have with the 
understanding that they will continue to run up into various limitations 
in the long term. 

You need:
* a set of permissions for handbook maintainers
* an idea of what you want to do with comments
   * where do you want to display them?
   * a way to be notified of new comments
* a custom menu block that will make maintaining easier (optional)
* a place to work on pages collaboratively (optional?)
* happy thoughts (required)

Anisa.


Dries Buytaert wrote:

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