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
