Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-11 13:07:01

Edward Diener wrote:

> As you say the tools are there. But I do not think the difficulty of
> some of the docs are a matter of tools.

+1

Although tools can always be made better
I think our tools are "good enough" for what we need.
Although I've spent a significant effort in understanding and
using these tools - I don't have a heck of alot to add to
what other's have observed.

I'm really thinking of reaching more common ground about what
constitutes useful documentation which can be produced with
a reasonable effort.

Personally I would like to see reference documentation in all
libraries look more or less like the pages in the SGI stl documentation

I have to say I think this discussion is very productive. I don't know
that it will actually result in better documentation, but it makes me
feel that I'm not alone in my concerns about this.  It also points
out that there isn't wide agreement about what documentation
should look like.
.
Robert Ramey