Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-10-07 19:59:01

On 10/7/2017 12:25 PM, 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.  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.

The major problem with library docs is always that programmers become 
too lazy to explain what the various things are that library actually 
does and what the constructs are to achieve each of those various 
things. Instead, for too many programmers, library documentation is 99% 
examples and a reference, the latter being nothing more than a listing 
of constructs which can be used, with no explanation of when or why one 
might want to use them. That's it for an awful lot of developers ! And 
as long as programmers in general consider that as adequate 
documentation, library developers will continue to follow that model. 
Even when you point out to programmers that such documentation is 
inadequate for end-users who actually want to use your library, the 
usual response is just bafflement that the end-user doesn't "get it".

I understand that programmers do not want to write documentation, but 
want to create really nifty and useful libraries and programming 
constructs. I understand that many developers are not native English 
speakers and find it quite onerous to write documentation in a secondary 
language which they can almost never know as well as their own primary 
language. I sympathize with both these problems. But unless docs can 
explain to end-users what is useful about a library and how that 
usefulness translates to the constructs of that library, library 
documentation will not be adequate for a great many intelligent 
programmers.

I feel like an old dinosaur writing this. The current age of computer 
programming expects so little of documentation that I am probably 
already obsolete in my documentation needs. But I hope programmers will 
try to understand that the most brilliant library is useless if it 
cannot be understood or, conversely, if understanding it takes such an 
inordinate amount of end-user's time that he just gives up in trying to 
use the library.

I think very little of this has to do with tools per se. I am certainly 
for the best tools which anyone finds easy and adequate to use. Rather 
this problem has to deal with the approach to documentation as a means 
to explain what one offers as library functionality.

> 
>>> 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