Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-07 16:25:24

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.  I have a lot to 
say about this very phenomenon in my recent presentation at cppcon 2017. 
Hopefully the video will be available shortly.  I wasn't totally happy 
with my presentation, testimony to how difficult is to capture the 
problem and address it.

There have been a few recent boost library submissions which have 
suffered in this area to the extent I believe they may have turned a 
possible acceptance to a rejection.  In one case I believe that a 
previously rejected library was accepted and a large part of that change 
of assessment was due to much improved documentation.

So, contrary to what one might think, I do believe we are making some 
progress in this area.

>> and moreover one which finally can parse
>> the worst possible C++ metaprogramming without blinking because anything
>> clang can parse can be documented.
> 
>    Just because the parser can handle it, doesn't mean that
> it's a good idea.  For example, in documentation, I always
> hide complex SFINAE, and instead provide an English description
> of the conditions.  In general, I find the more complex the
> metaprogramming is, the more tweaking is required to turn
> the doxygen output into something sane.  This is rarely because
> doxygen can't parse the code, but is rather because the raw
> definitions in the source are not very human-friendly.

The question of how to document/explain certain C++ constructs such as 
template parameters, concepts and meta functions is an interesting one. 
Tools like Doxygen and others don't address this.  It's not obvious and 
not described by any "tutorials" on documentation.  Actually, there 
isn't even a concensus.  In a recent review, I complained that 
requirements on template parameters weren't document.  The library 
submitter countered that it wasn't necessary because the code contained 
static_asserts to enforce (otherwise undocumented) requirements.  Even 
the C++ standard calls for this - yet it's often skipped.  SGI documents 
describe documentation standards in detail - but this is almost ignored.

>>
>> You can see our joint efforts so far for Outcome v2 at
>> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
>> written so far, it's all him.

Andrezej is a great writer who understands all this.  I know this 
personally from

a) reading his blog
b) going back and forth with him on the documentation structure of the 
safe numerics library.  Though this effort is better than most, there 
have been a lot of problems with this and he is one of the few that 
understands this stuff.  We share a common view as to what documentation 
should be.  So his criticisms are on point and almost always correct. 
He is also very meticulous which helps me a lot.

To summarize:

a) Our (boost and C++ generally) problem is not rooted in the tools, 
though the tools don't help much.

b) There is growing recognition that it's a serious problem both in 
boost and C++ generally.

c) In reviews, we're more critical of documentation than we used to be 
and suggestions to improve it are more constructive.

So things are slowly getting better. I'm optimistic about the future.

Robert Ramey