Re: [boost] Indexing of documentation (Was: Why Boost.Build?)

Subject: Re: [boost] Indexing of documentation (Was: Why Boost.Build?)
From: Artyom (artyomtnk_at_[hidden])
Date: 2011-03-27 16:02:33

> Edward Diener wrote:

> 
> > The documentation is generally poor because it  does not attempt to
> > explain all of the information in Boost Build, and  what it does explain
> > is spread out in many different areas of the  documentation to the
> > detriment of the documentation's organization.  Finally, what passes for
> > an index in the documentation indexes  practically nothing and is
> > essentially completely worthless.
> 
> I  think it would be great if somebody who knows how to write  documentation
> could write some guidelines how to produce usable index. Every  time I
> think about adding anything, I am not even sure what should be  primary
> index term, and what should be secondary ;-)
> 
> -  Volodya
> 

Volodya,

I think you should write the documentation as you write it for any
software or library.

1. General Concepts:
   a) Syntax
   b) Rules
   etc.

2. Tutorial How to do common stuff:
   a) Build a program
   b) Build a library
   c) Build a test
   d) Configure things conditionally
   e) Create extensions
   And so on.

   Pass on common features of Autotools, CMake, SCons
   and make sure users can easily figure out how to do.

3. **Full** reference documentation:

   - Properties
   - Modules
   - Rules

   And so on. This is even more important
   then tutorial because user and search
   for specific functions rules if they documented
   but he can't if there is no docs.

   As example I can provide ICU, their tutorials
   are very poor and basic but their reference docs
   are really great.

And given a fact that 1 and 2 mostly exists
you should work on 3rd part.

Also I may ask is there a chance to connect Doxygen
with BBv2? It may make this task much easier.

Artyom