Re: The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2005-01-28 11:32:23

Vladimir Prus <ghost_at_[hidden]> writes:

> Doesn't "Builtin Modules" title cover as much as "Builtin rules"?

Yes, but the layer beneath it (its subsections) will have coarser
granularity. So it will have fewer subsections.

>> > 2. Want to include overview docs
>>
>> What are "overview docs," and where do we want to include them?
>
> An example of "overview docs" is 
>
> http://boost.org/boost-build2/doc/html/bbv2/advanced/jamfiles.html#bbv2.advanced.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.

>> > I must admit I now don't understand how you suggest to restructure
>> > the current "Tutorial" and "User documentation" section. Could you
>> > explain that again?
>>
>> I can only repeat myself with a little extra:
>>
>> The tutorial should become the beginning of the user guide chapter,
>> and the redundancy between them should be removed. The user guide will
>> be a narrative description of how to use Boost.Build that deepens
>> progressively, beginning with the material you need to know in order
>> to get started using it effectively (fundamental concepts). The
>> current scope of the chapter is not bad, but as long as your goal is
>> that the chapter will *not* attempt to provide complete coverage, some
>> things should probably be pruned or moved to another area. For
>> example, there's no need to cover "variant" as a feature. Probably
>> the final part of the chapter should be divided into major topics
>> organized around builtin modules like testing.jam, python.jam,
>> boostbook.jam, install.jam, etc.
>
> Okay. Then what about this:
>
> User manual
>
> Tutorial
> <all the current content>

I forget what that is, so it's hard to comment.

> installing
> testing
>
> Fundamentals
> Jam syntax
> Declaring main targets
> Declaring project attributes
> The build process
>
> Configuration
> Builtin target types
> Auxilliary Jamfile rules 
> Builtin features
> Differences to Boost.Build V1.
>
> 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!

>> > Another example of my difficulties -- in "Writing Jamfiles" I
>> > mention conditional requirements. You've added a comment that it's
>> > covered in tutorial. Yes, but on the other hand "Writing Jamfiles"
>> > is supposed to be an overview section.
>>
>> I don't know what you mean by "an overview section."
>>
>> It's problematic, incidentally, that the docs have 2 sections with
>> that title.
>
> You mean the "Writing Jamfiles" title? 

Yes.

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

>> > If I remove any mention about conditional requirements, user can
>> > only learn about them from the tutorial, which I find not so good. I
>> > can just link to tutorial section -- is that OK?
>>
>> Conditional requirements are a fundamental concept of Boost.Build, so
>> they should be covered in the section on fundamentals. 
>
> And consequently, they should be moved out of the tutorial section? 

Probably.

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

> If that's the case, conditional requirements must remain in the
> tutorial section.

You need to decide what you're calling "tutorial." This is part of
the reason I've thought there were too many different chapters. If
the whole user guide has a tutorial flavor, you can have a "hello
world" type getting started section and then cover fundamentals and
continue to deepen throughout the user guide.

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