Re: The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2005-01-27 12:47:33

Vladimir Prus <ghost_at_[hidden]> writes:

> On Wednesday 26 January 2005 21:38, David Abrahams wrote:
>
>> >> > We already have user/extender docs separation -- which is good, but I
>> >> > think we should strive to avoid the user manual becoming a set of 30
>> >> > sections without further structure.
>> >>
>> >> It would be a good time to look at the topics you're covering there and
>> >> try to organize them into a hierachical structure, while simultaneously
>> >> looking for what's missing that you want to cover (otherwise you might
>> >> find some isolated bit that will really be accompanied by lots more but
>> >> that looks too small to stand in a section by itself).
>> >
>> > There's still a problem for me. Say, we have section "Builtin rules"
>> > which describes "alias", "unit-test" , installing and so on. If we make
>> > each rule into a separate section, documentation looses any structure. If
>> > we retain the current structure, then how a user which wants to install
>> > things can find the relevant section?
>>
>> ?? That's why I was suggesting you make an outline of everything that
>> should be covered there and try to organize it into hierarchical
>> structure. Somehow your reply here sounds as though you didn't
>> understand me.
>
> 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.

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

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

> 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 think it's reasonable to assume that there will be a fair amount to
>> cover about installing (more than just one rule), and likewise about
>> testing rules. So I think these should be organized into "builtin
>> tools" or "builtin modules" based on the sort of work they are
>> good for:
>>
>> ...
>> Builtin Modules
>> test
>> install
>> python
>> ...
>> ...
>>
>> Probably "alias" would fall into a section about general utility
>> rules... although, it seems to serve so many purposes that a separate
>> section on alias and how to use it might be a good idea.
>>
>> > Can we assume he'll just right to "builtin rules"?
>>
>> He'll just ______ (jump?) right to "builtin rules?"
>
> Right, "jump".
>
>> > Of consider "Writing Jamfiles" section.
>>
>> ["Of" doesn't belong there]
>>
>> > If a user wants to know the syntax for declaring main target
>>
>> You mean the "common syntax?"
>
> Yes.
>
>> > will he guess that he should read the "Writing Jamfiles" section?
>>
>> Well, in some sense you can't do anything without understanding how to
>> write Jamfiles, so it wouldn't be so bad if you had to read that. But
>> it also seems as though the common syntax for main targets is a
>> fundamental organizing principle of Boost.Build. So there should be a
>> "fundamentals" section that describes the main concepts (the domain
>> abstractions) of Boost.Build and covers basics like the common syntax.
>
> 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?

> How do we structure the docs, then? First some tutorial section, then 
> "fundamentals", then "builtin rules"?

As I said, I don't think "builtin rules" is a good section title.

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

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

> 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. 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. There's also invoking and extending
Boost.Build, but the first is a (comparatively) small topic, and the
latter is needed (comparatively) rarely.

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