Boost logo

Boost :

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-01-24 09:52:00

--- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
> ----- Original Message -----
> From: "bill_kempf" <williamkempf_at_h...>
> > 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
> >
> > comments from other Boost developers and users.
> >
> > Some info on this upload:
> >
> > * There are actually two sets of guidelines provided. The first
> > with the general structure of documentation and is taken mostly
> > 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
> > apart the documentation and HTML (even if Boost doesn't care to
> > this, the documentation will be useful for me any way, so I'd
> > appreciate the feedback).
> Bill,
> I have a mixed reaction to the first set of guidelines. It will be
> helpful to anyone (like you) who's aggressively seeking entry for
> 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
> y'know, "hello, lib".

No disagreement from me here. I actually think that most Boost
documentation needs a mix of both "user friendly" documentation and
the more strict "standardese" style of documentation. I'm more then
willing to work on adding more structural documentation for the "user
friendly" stuff if you or anyone else has recommendations.

> 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-
> set of guidelines written.

OK, I'm fine with this as well. But I'd request a volunteer for
the "happy-friendly" set ;).
> 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.

The "hello lib" section is the "overview.html" template. I think it
really does cover what you want, but quite likely the template and
the description need some work to make this more obvious.

BTW, if you're not so fond of the structural document then do you
truly like the header.html template? Something is not quite meshing
Thanks a lot for the comments.

Bill Kempf

Boost list run by bdawes at, gregod at, cpdaniel at, john at