Re: Writing Boost Documentation

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-01-24 10:30:04

--- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
> 
> ----- Original Message -----
> From: "bill_kempf" <williamkempf_at_h...>
> 
> 
> > 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.
> 
> It's a question of emphasis. At least the header templates contain 
a section
> for happy-friendly docs, but the structure document doesn't even 
mention
> them.

The "summary" specifications in the structure document directly 
relate to the (minimal) happy-friendly section in the header.html 
template.  So it sounds to me like your object isn't so much what's 
there, but what's not *obviously* there.  The structure document was 
taken nearly verbatim from the standard, so it's admittedly not 
overly clear on some of these points.  Can we clean up the way 
structure.html is written to give the emphasis you want?

Note: I still think there's room for even more happy-friendly 
documentation than is currently accounted for in any of the 
documentation or the templates.  That was at least part of the reason 
for posting this in the rough draft form it's in.

> I would need to expand on the overview section a lot, but it's a 
place
> to start. Also, the reference manual section is absolutely 
neccessary and
> it's great to have templates to work from. I got the impression 
that there's
> a lot in the structure document which isn't directly implied by your
> templates.

I'm not sure I know what you mean by this last sentence.  If you said 
it the other way around it would make more sense to me :).  The 
templates are an attempt to codify *everything* stated in both the 
structure documentation as well as the design documentation.  The 
header.html template has some holes, as I originally stated, since I 
can find no examples of how to format certain things to use as a 
starting point (for example, macros, values, etc.).

Bill Kempf