Re: Writing Boost Documentation

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

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-
friendly
> 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 
there.
 
Thanks a lot for the comments.

Bill Kempf