cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Berin Loritsch <blorit...@d-haven.org>
Subject Re: [RT] The Cocoon Handbook
Date Thu, 24 Jun 2004 15:54:50 GMT
Nicola Ken Barozzi wrote:

> Tony Collen wrote:
> ...
> 
>>  >> The Solution <<
>> I propose we create a free, high-quality electronic book (entitled 
>> _The_Cocoon_Handbook_), which will eventually replace the mess of docs 
>> we currently have.  It will be in DocBook (possibly simplified) format.
> 
> ...
> 
> Let's not make this a technology issue, it's a "people" issue.
> IOW, it's not (only) the doc system that sucks, but it's the doc writers 
> that are missing.
> 
> 1 - The first thing we need IMNSHO is to define a structure of this 
> book: The sections, the chapters.
> 
> 2 - Then we can take the existing docs and put them into place in this 
> structure till there are no more, eventually enlarging the structure to 
> make them get in.

All I can say is "Write On!" (pun intended).

Seriously, having a good organizational structure helps writing
comprehensibly.  The structure does not need to be set in stone, but it
does need to be there.  The biggest problem is getting writers.  It
really doesn't matter how it is written as long as the information gets
out there.  Heck, use Wiki format to rough it in!  It's easy and you
don't have to worry about this tag or that.  As long as the important
information is stuck in people's heads and not in some easily extracted
electronic format then it doesn't matter how elegant the doc build
system is, it is still irrelevant.

Question is, who is going to do the writing?

-- 

"Programming today is a race between software engineers striving to 
build bigger and better idiot-proof programs, and the Universe trying to 
produce bigger and better idiots. So far, the Universe is winning."
                 - Rich Cook


Mime
View raw message