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