Boost logo

Boost :

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

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.

Boost list run by bdawes at, gregod at, cpdaniel at, john at