Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-10-07 22:09:48

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

There is currently a mini-repeat of the Outcome v1 review happening on
std-proposals. Many of the same points being made there by the
uninitiated expert as was made here back in May. Same progressions of
understanding. Same arrival at the same conclusions. It's encouraging.
But also slightly surprising, the simpler the concept, the harder it
seems to become for people to grok it in a strange way.

But it also contradicts what you just said. You can very easily explain
a library e.g. ASIO. It's a networking library. Done. But does that have
much relation to its good or bad design? Same goes for Expected|Outcome.
It lets functions return a T|E, like std::variant. But is the Expected
or is the Outcome design good or bad? What are the merits and
disadvantages of each design decision? How do you weigh them?

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

Standardese as in the word soup they put in the C++ standard is not
documentation. I tried my hand at writing some of it for the operator
try proposal, and immediately got nit picked on lots of bits in it. I'm
no language lawyer. I care about *themes*, shapes, forms, fit like any
library not compiler developer. Nit picky detail for me is just
punctuation, to be added or removed as needed so long as it doesn't
break ABI.

Which is why I'm not on WG21! Nor would be much use there I should think.

But Standardese the tool for generating reference API docs is a large
improvement on doxygen, and once it matures quite a bit ought to be very
useful for Boost type C++. Be appalled, after all, at how useless the
doxygen "extract all" dump of Outcome v2 is:
https://ned14.github.io/outcome/doxygen/namespaceoutcome__v2__xxx.html.
Far too much implementation detail, it's useless.

But Standardese the tool once we get it working ought to chop that very
nicely down into the "just right" balance between detail and
need-to-know-this. And being pretty in presentation and disability
friendly doesn't hurt.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/