Re: [jamboost] The right documentation structure.

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-30 06:49:00

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. 

> The chapter should be renamed to "User Guide." 

Or, you mean "User Guide" chapter, starting with "Tutorial" section.

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

I though about this too and decided this would be a good thing. The current 
User manual has too many subsections.

> The current scope of the chapter is not bad, but 
> given 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. I would move
> the tiny bit of coverage of testing, and all mentions of
> hardcode-dll-paths, to a special section or separate chapter called
> "Testing and Debugging Software with Boost.Build."

Maybe hardcode-dll-paths deserves a tip in user manual but testing can be 
moved to separate section. The only question I have is what other section 
there will be. Say, where the overview of build process:

http://boost.org/boost-build2/doc/html/bbv2/advanced/build_process.html

belong?

What I'd like to avoid is a manual in style of SCons. The problem with it is 
that the structure is very flat, and it's very hard to find anything (at 
least for me). Of course, section names like "Less Simple things to do with 
Builds" contribute to the problem ;-)

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.

> The "Detailed Reference" is mostly on target and correctly focused, but
> you should take care to keep "HowTo" information out of it. For
> example, the coverage of generated headers belongs in the User Guide.

I agree to this.

- Volodya