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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-27 10:19:46

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?
- Even is hierarchy is not too deep (say "test" under "builtin rules"), you 
still loose random access to docs. You can't immediate find "test". Maybe, 
some kind of an index can help.

> 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.
2. Want to include overview docs

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

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?

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

- Volodya