On 07/10/2017 17:25, Robert Ramey via Boost wrote:
On 10/6/17 8:12 PM, Steven Watanabe via Boost wrote:
If we can get it working, it'll be a whole new age of "easy" for writing docs for complex C++ codebases,
Er, I've always considered the hard part of documentation to be the organization and content rather than specific tools.
So, so, so, true. I huge problem these days is that the attractive presentation of documentation gives the impression that documentation is well done. It's very, very misleading. It's a plague.
Indeed, but there's another issue here I would like to raise: * How do you know when a library is well designed? The answer for me at least in part is: * Can I, starting with a blank sheet of paper, easily explain what this does? I've lost track of the number of times I've redesigned something because it failed that test. The problem I see then, is that tools that extract documentation direct from code have the effect of disengaging the authors brain from the task of explaining what their code actually does. Well it does for me anyway ;) I've also come to the conclusion that standardese does not make good documentation - despite having authored more than my fair share. And now I'll get back to lurking again.... John. --- This email has been checked for viruses by AVG. http://www.avg.com