[boost] Documentation Redux (was Re: Boost 1.36.0 release notice)

From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2008-08-18 04:43:47

On Mon, Aug 18, 2008 at 4:17 PM, John Maddock <john_at_[hidden]> wrote:
> Robert Ramey wrote:
>>
>> LOL - of course it does.  If regression testing were setup for
>> boost tools, they would be demonstrated to be functioning as
>> expected before they were used in the actual release process.
>> Had this been procedure been in place, the issue raised
>> above would not have occurred.
>
> This is a good point, in fact is there any reason why the doc build
> shouldn't be part of the regression tests?
>
> Ah.... but it requires external tools that might not be available
> (especially now that accumulators has introduced a dependency on Latex and
> Ghostscript) :-(
>

I think this may be something that should be solved by policy rather
than technical solutions. For instance, libraries follow a certain set
of guidelines regarding how the code is organized (namespaces, macro
names, type names, directory structure, directory naming, etc.). Why
shouldn't there be guidelines regarding the documentation of these
libraries? I know the guidelines are minimal by design (for example
should be in HTML and/or PDF) but right now it's getting quite
unwieldy -- and arguably, the documentation is becoming as important
as the actual code is.

I understand that documentation is largely an author/maintainer
domain, and that currently the choice of documentation tools used is
left to the author/maintainer. If we can somehow standardize on a tool
set and help authors/maintainers convert their documentation from
their current format to another then maybe we can make some progress
regarding fixing the documentation-building/generation process and
"improvement" of the library documentation. This also allows
interested contributors to (more easily) learn the tools required and
help out in the "improvement" of the documentation effort.

Traditionally, Wiki's have worked well for other projects. Should
Boost start doing this too, and just export documentation from the
Wiki into properly cross-linked HTML pages in release builds? I
understand Trac has the Wiki functionality already available -- should
we start using it for documentation?

Another option (that I think Dave Abrahams has been doing) is to use
RST [0] to make writing/reading the source documentation easier than
having to rely on Boostbook+XSLT (which I personally think is a
brittle tool-chain).

Quickbook is also a nice documentation language to use, but the
reliance on Boostbook+XSLT makes it harder to pull-off. I don't know
though if Quickbook can be made to generate HTML directly instead of
XML. Joel?

I understand there's also a Boost Documentation project. Anything
happening in that front?

[0] - http://docutils.sourceforge.net/rst.html

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.