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

On 11/4/2016 6:28 PM, Vinnie Falco wrote:

On Fri, Nov 4, 2016 at 6:17 PM, Edward Diener 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.