Re: [jamboost] Re: Docs structure

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-14 09:06:28

On Tuesday 14 December 2004 16:46, David Abrahams wrote:

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

I don't agree. Tutorial is more like ad. Users read it to get overall 
impression of features. I don't expect it to be very useful for regular work.

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

Why 3 or 4. Tutorial should require no change at all, unless we introduce 
something extra cool. Most user visible feature require tweaking user docs 
and maybe reference.

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

Is it possible without getting unreadable? Say, can be add syntax of target id 
into user documentation? 

> When certain 
> subjects demand more attention, we can add an appendix that we reference
> from the main part of the manual.

That's almost how user manual/reference work. User manual links to reference 
when details are too numerous to include in user 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.

Sure.

- Volodya