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

Subject: Re: [boost] [process] Formal Review starts today, 27 October
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-11-04 20:55:47

On 11/4/2016 6:28 PM, Vinnie Falco wrote:
> 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.

I agree that good documentation requres considerable effort, and I thank 
you for describing your own attempts at it.