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.
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk