Re: [boost] Writing Boost Documentation

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-01-23 18:36:21

----- Original Message -----
From: "bill_kempf" <williamkempf_at_[hidden]>

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

<snip>

> 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,

I have a mixed reaction to the first set of guidelines. It will be extremely
helpful to anyone (like you) who's aggressively seeking entry for their
library into the C++ standard. As far as I know, no such comprehensive guide
to standard language and convention has ever been assembled. However, as we
probably all know, the standard language and convention leans towards the
ascetic rather than the user-friendly. IMO, every library's documentation at
boost should start with some simple examples that show how it's used;
y'know, "hello, lib".

Also, I this these guidelines would be quite daunting to most people
thinking about submitting their first boost library (they were a bit
daunting for me). They make it sound like you really should learn how to
write for the standard before you think about documenting your library. I'd
like to see the standard language issues moved to a section called "getting
ready for standardization" or something, and a more general, happy-friendly
set of guidelines written.

I really like the 2nd set of guidelines (the HTML templates et. al). That
will be a big help in my upcoming work... though, again, where's the "hello,
lib" section? I suggest a quick survey of existing boost documentation to
see what really works well, and that we then "codify existing practice", so
to speak.

-Dave