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

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

On Thursday 27 January 2005 20:47, David Abrahams wrote:

> > Maybe. The are two issues:
> >
> > - the word "outline" already implies some hierarchy to me. Maybe,
> > because I associate it with "outline" mode in Emacs. I suppose you
> > mean just a list of topics?
>
> No, I mean a hierarchically-organized list of topics. You can start
> without the hierarchy and discover natural groupings after you've
> established all the important elements, though.

Ok.

>
> > - Even is hierarchy
>
> ^^
> "if the"?
>
> I'm picking nits because this stuff creeps into the docs and makes
> them harder to read. Two in the same sentence can make it completely
> incomprehensible.

I understand and will try to do better.

> > is not too deep (say "test" under "builtin rules")
>
> "builtin rules" is probably not a good topic, because it encompasses
> too much. That's why I like the "Builtin Modules" idea below.

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

> > you still loose random access to docs. You can't immediate find
> > "test". Maybe, some kind of an index can help.
>
> Of course it can.

I'll start adding docbook markup for index, then.

> > Then, we:
> > 1. Want to start user manual with a simple example like "hello" word, to
> > avoid scaring users away.
>
> I want to start the _tutorial section_ of the user guide (probably the
> 1st section) with a simple
> example like "hello world."
>
> > 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.

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

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

> > 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? 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? If that's the case, conditional 
requirements must remain in the tutorial section.

> I don't think 
> "Writing Jamfiles" is a good topic anyway. Almost everything that you
> do with Boost.Build is "writing Jamfiles," so it doesn't make for a
> very good distinction. 

I agree now.

- Volodya