Re: [boost] [process] Formal Review starts today, 27 October

Subject: Re: [boost] [process] Formal Review starts today, 27 October
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2016-11-04 18:28:01

On Fri, Nov 4, 2016 at 6:17 PM, Edward Diener <eldiener_at_[hidden]> wrote:
> It always baffles me when a developer provides useful
> functionality in his library but does not bother to explain what that
> functionality entails. Is it laziness ? Is it tiredness ? Is it an inability
> to write a few coherent sentences in English because of lack of education or
> that English is not the developer's native language ? I just don't know.

I can help answer that question, at least for how it pertains to me.
My inability/anxiety to write is directly proportional to the degrees
of freedom for the text in question. The more constrained, the easier
to write. The more freedom, the more difficult. I can easily write the
first line of a Javadoc comment, explaining what the function does in
a sentence. Similarly I can fill out the @param list with not much
trouble. Adding extra paragraphs for the verbose description requires
more thought but it is doable.

Sometimes though, the longer description requires above average work
and that's where anxiety / writer's block starts to creep in. Do we
talk about exceptions first? Undefined behavior? Where in the
description would be a natural place to put an example? How big should
the example be? Do we make the example compile completely stand-alone?
Do we assume there's a "using namespace" in there?

Then we get to the part of the documentation which is unstructured and
pure exposition. I'm talking about the part where there are no guide
rails or Javadoc. Just an empty [section] in the .qbk file and oh -
hey, now its time to write! I try to write Javadocs as I go because
they are easy to update as needed. But I don't make a large investment
in exposition until the library has reached a certain size and I have
some confidence that things aren't going to change too much. With pure
exposition there are even more choices to make. How to start the
conversation? Do we start with an example? Explain the motivation? How
detailed do we make this explanation? Do we split the advanced use
cases to another section where they won't confuse people or do we keep
everything related to individual functions and classes together
regardless of complexity?

By the time I'm writing exposition, I've feel like I've already just
finished a programming marathon and quite exhausted. Its tough to
muster up the remaining creative energies to write. Writing code is in
some ways easier than writing exposition. The compiler warns you or
gives you an error if you made a mistake. And you can verify that the
program is correct by writing tests and running it. Analagous systems
exist for exposition: proof readers, friends and family, other
programmers reviews. But they lack the certainty and responsiveness of
the compiler.

I can't speak for others, but I am certainly not lazy. Perhaps
"tiredness" is part of it. Good documentation requires considerable
effort.

Regards