Re: Documentation structure

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-23 12:45:39

Vladimir Prus <ghost_at_[hidden]> writes:

> On Thursday 22 September 2005 19:36, David Abrahams wrote:
>
>> >> What about hierarchy like this:
>> >>
>> >> 1. Getting Started
>> >> [ includes installation and tutorial, with 1-2 small, but complete
>> >> examples (points 1. and 2.) ]
>> >
>> > What I'd prefer is this:
>> >
>> > - "Hello world" -- a single Jamroot project
>>
>> Wait, wait! As Andrey recently wrote:
>>
>> Also, at this point the user doesn't know what are toolsets and
>> projects. So we should restructure the documentation and put an
>> introductory chapter before the Installation chapter. It's
>> impossible to install BB without understanding the toolsets.
>>
>> So clearly we need to lay some groundwork before we do "Hello World,"
>> don't we?
>
> Well, I tend to dislike documentation that don't have a simple example right 
> away. We can remove "project" and everything else from "Hello, world" 
> section.

What about that section "for managers" that was discussed earlier?
That contains some talk about the major concepts of BB. IMO it's
crucial to have such an introduction, actually for everyone, that
says, basically

"Boost.Build isn't like the other build systems you've probably
used... it's built around these concepts ____ which yield these
benefits _______ ."

> In fact, version of "Hello, World" what Alexey has posted:
>
> http://article.gmane.org/gmane.comp.lib.boost.build/10507
>
> seems pretty good to me.

It's pretty good, but I think people will be confused by the long
paths on the generated targets, so we need something to allay their
inevitable concern.

>> I think you ought to go back and think about the various things you're
>> talking about covering in this section and break each one down in more
>> detail into sub-elements, then see how they should be organized. In
>> fact, this whole outline needs more detail [I see you try to do that
>> below -- put that information in context]
>
> In fact, I'm now thinking that we should try flat structure for the whole 
> "User manual section". 

Maybe a "flatter" structure, but not a flat one, please. No matter
what you do, there should be sections and subsections and various
points you want to make within each subsectoin. If the whole manual
is just one paragraph after another with no grouping it will be
impossible to use. So, please, let's construct a proper hierarchical
outline for this before we go any further.

>> > I think this organization is fine. The biggest question now is
>> > detailed structure of section 2. Topics should include:
>> >
>> > - Language reference (current (just added)
>> >
>> > http://boost.org/boost-build2/doc/html/bbv2/advanced.html#bbv2.advanced.j
>> >am_language) - Features and properties
>> > - Configuration
>> > - Declaring targets (current
>> > 
>> > http://boost.org/boost-build2/doc/html/bbv2/advanced/targets.html) -
>> > Builtin features
>>
>> I don't think that makes sense. Are we really going to introduce
>> people to features and properties in general as a separate topic
>> without showing them builtin features?
>
> All builting features? There's a lot of them.

Not necessarily all of them, but you need to introduce some of them
around the time you describe features and properties. Maybe that was
your plan all along. More detail in your outline below the
description of features and properties would be a good idea, and might
have prevented me from thinking you weren't going to mention them
before.

>> > - testing rule
>> > - install rules
>> > - low-level rules (make and notfile)
>>
>> Hmm, I'm not sure these should be in separate topics without an
>> overarching topic, "Globally Available Rules" or something. I don't
>> quite like the wording, but the point is to distinguish these rules,
>> which are automatically injected into Jamfiles for use without
>> qualification, from any old "builtin rule."
>>
>> > - declaring project constants
>> >
>> > Any additions?
>>
>> Explain target references early on.
>>
>> Be sure to explain where target and project references are required
>> and clearly distinguish them from filesystem paths.
>
> Ok, I'll try to prepare a more detailed outline and post it on Monday.

I'll try to post something on this that will be waiting for you on
Monday when you get in.

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