Re: [jamboost] Re: The right documentation structure.

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-31 03:17:28

On Friday 28 January 2005 19:32, David Abrahams wrote:

> > http://boost.org/boost-build2/doc/html/bbv2/advanced/jamfiles.html#bbv2.a
> >dvanced.targets
> >
> > It mentions:
> > 1. "Common syntax" for declaring main targets
> > 2. Conditional requirements and alternatives
> > 3. Inline targets
> > 4. The glob rule
> >
> > Essentially, it mentions almost everything you might need when declaring
> > a main target, so that user can know the list of features without reading
> > all of the docs.
>
> What you're getting at by saying "overview" still seems rather
> amorphous to me. I could interpret this as meaning "docs that cover
> everything in full detail." Try to figure out how to say what you
> mean more precisely; it will help both of us.

Try 2: "overview" is a combination of:

- fundamental concepts and how they relate together
- quick mention of all features
(e.g. all the various details of defining a main target).

> > This adds "installing" and "testing" and rearranges other sections a bit.
> > Will that work?
>
> I'm not sure installing and testing belong in the toutorial. By the
> time you're reading about those topics you should surely have learned
> the fundamentals!

The same can be said about any other topic, except for "Hello, world". I think 
putting a large "Fundamentals" section too early will scare away the user.

> > I intended the structure of "Detailed reference" to mirror the
> > structure of "User documentation". That's why both have "Writing
> > Jamfiles" and "Build process" sections.
>
> It's confusing; at least it was for me. Unless the mirroring is
> perfect and your intentions are spelled out, I think it's best
> avoided.

OK.

> > I don't like that much. Guess we need to decide what is the role of
> > tutorial. Can we assume that user can read tutorial, start using
> > Boost.Build, and never need to look at the "Fundamental" section?
>
> No! The tutorial should be enough to get started, but not enough to
> really understand the system. For that you need fundamentals and
> deeper/broader information about the system that puts those
> fundamentals into play.

Then, I'll try to make tutorial into a short tour, starting from first project 
and ending with installing. 

- Volodya