Writing Boost Documentation

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

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

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

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

Bill Kempf