Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: John Maddock (jz.maddock_at_[hidden])
Date: 2017-10-07 17:25:21

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