Re: The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2005-02-01 09:29:27

Vladimir Prus <ghost_at_[hidden]> writes:

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

That's why the set of concepts qualified as fundamental should be
small.

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

Sounds reasonable.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com