The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-29 21:05:30

Volodya,

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.

The chapter should be renamed to "User Guide." 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. 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."

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.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com