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
I think you should write the documentation as you write it for any
software or library.
1. General Concepts:
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:
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.
Boost list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk