Re: The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-30 14:43:47

Vladimir Prus wrote:
> 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.

>> The chapter should be renamed to "User Guide." 
> 
> Or, you mean "User Guide" chapter, starting with "Tutorial" section.

I'm not sure you need to label anything Tutorial as long as there's
introductory material saying, "the beginning of the User Guide is
designed to get you started as quickly as possible. By section XX you
should have acquired all the major concepts needed to begin using BB
effectively."

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

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.

> in user manual but testing can be 
> moved to separate section. 

> The only question I have is what other section 
> there will be. 

Where?

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

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

I found the Scons manual difficult too.

> Of course, section names like "Less Simple things to do with 
> Builds" contribute to the problem ;-)

Yes.

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

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