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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-26 04:40:30

Hi Dave,

> >> I am now confident that I know how the docs should be structured. The
> >> tutorial is pretty good (or will be as soon as soon as you go through
> >> our edits), but there's a terrible amount of redundancy with the next
> >> chapter. The tutorial should become the beginning of that chapter, and
> >> the redundancy should be removed.
> >
> > Do you mean that the tutorial and current "User manual" should form one
> > section? Or simply that they should form a logical sequence with no
> > duplication? Either variant is OK, I'm just trying to clarify.
>
> Either variant is OK with me, too, but I had the former in mind.

Ok, let's try this.

> > Maybe hardcode-dll-paths deserves a tip
>
> I'm guessing a brief mention in a table (if anything) is more
> appropriate. The user guide shouldn't go into an explanation of why you
> might want to use the feature. Someone who knows about the issue will
> know why. Someone who doesn't should use the built-in testing rules
> first, and only resort to hardcode-dll-paths as a last resort.

My edits in tutorial.xml drop hardcode-dll-path completely. After all, it's a 
nice feature of Unix that just works, so beginners should not care.

> > Say, where the overview of build process:
> >
> > 
> > http://boost.org/boost-build2/doc/html/bbv2/advanced/build_process.html
> >
> > belong?
>
> It's fine for that to be in the User Guide, but it has to be edited. It
> has too much low-level information in it and makes assumptions about the
> user's understanding of BB internals. I haven't checked in my notes
> there yet.

I went though your notes there and I think understood most of them. I'll now 
edit advanced.xml.

> > 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? Can we assume he'll just right to "builtin rules"?

Of consider "Writing Jamfiles" section. If a user wants to know the syntax for 
declaring main target, will he guess that he should read the "Writing 
Jamfiles" section?

- Volodya