Re: Docs structure

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-14 08:46:08

Vladimir Prus wrote:
> 
> Dave wrote:
> 
>> I understand that, but the docs are getting to be a scattered sprawl
>> with little or no coherent organization. It's very unclear where you'd
>> go to find out any particular answer you need. That needs to be not
>> only stopped, but repaired. So I really don't want it to get worse.
> 
> I envision the structure to be
> 
> 1. Tutorial (just nice examples for new users)
> 2. User documentation. It should document everything, but in a verbose way, 
> and without all the details.

The tutorial and the user documentation, as they stand today, cover much
of the same ground. I think the tutorial material should be merged into
the user documentation, and we should start the user documentation with
a simple tutorial walkthrough of a "hello world" and proceed a slightly
more complex example using libraries.

> 3. Reference (has all the details for user visible features, but too dense for 
> general users.

I am guessing that we don't have the time or energy to maintain this in
addition to the User Documentation. The structure as you describe it
here means that every time something changes you might have to edit 3 or
4 different sections of the docs. We should limit that to 1 or 2. So I
propose that we try hard to get the neccessary details into the user
documentation in a way that's readable and coherent. When certain
subjects demand more attention, we can add an appendix that we reference
from the main part of the manual.

> 4. Extender manual

I think this is extremely useful, but care should be taken that there's
no overlap between this material and the rest.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com