From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-01-22 11:58:22
I mentioned in another thread last week that I was working on a
document on how to write documentation for Boost. Well, I've
uploaded a first _draft_ to the files area at
http://groups.yahoo.com/group/boost/files/Boost Documentation.zip for
comments from other Boost developers and users.
Some info on this upload:
* The guidelines documented here are not meant to be requirements for
submitting libraries/documentation to Boost, and hopefully this is
made abundantly clear within its text.
* There are actually two sets of guidelines provided. The first deals
with the general structure of documentation and is taken mostly from
the C++ standard. The second deals with formatting guidelines for
HTML and provides several HTML templates for "quick starts" to
* Some things in the structure section are not fleshed out as much as
they should be, but the standard didn't provide guidelines either.
Help in fleshing out the obvious holes is much appreciated.
* Some things in the "header template" aren't fleshed out as much as
they should be. Unfortunately I could not find examples within the
standard to use as a guideline for the template (for example, only
classes and functions give any kind of structure for the
documentation because I could not find use of any of the other
* In the "header template" I've used the specific headings suggested
by the structure document, but the C++ standard instead uses headers
that are meaningful for a group of functions. Suggestions on how to
rework both the template and the documentation to illustrate how to
use more meaningful headers is appreciated.
* Links in all of the files have either been made local to the
directory structure in the Zip file, or link externally to the Boost
web site. Obviously if we decide to include this work in the Boost
site these links will need to be changed, but this is the best way to
illustrate how documentation will look when following these
I'd like to have some discussion about whether or not any of this
would be of interest for adding to the Boost site, as well as to pick
apart the documentation and HTML (even if Boost doesn't care to host
this, the documentation will be useful for me any way, so I'd still
appreciate the feedback).
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk