Documentation evolution (was Re: How to print a literal '.' as the first character in a line?)

[Dave Kemper]

On 5/2/22, Ralph Corderoy <ralph@inputplus.co.uk> wrote:
> Hi Branden,
>
> You seem to write many words when fewer would do, whether in emails
> or documentation.

I've noticed a distinct difference in Branden's writing style between
informal threads (emails, bug-report comments) and his documentation
writing, which tends to seek an economy of words unless that would
hamper accuracy or clarity.

> I find groff's documentation becoming increasingly chatty
> and waffly in tone.

Its chattiness is a judgment call, but I'd ask for examples of the
"waffly" claim.  There are countless places where he's clarified
things that the docs previously left unsaid or ambiguous, and he's
done a ton of making terminology more precise and consistent.  To cite
the example that originally launched this thread, the old docs termed
the \& a "zero width space," which Branden has changed to the
"non-printing input break."  It may not roll off the tongue as easily,
but it's more precise and descriptive about what the escape does: it
affects how input is parsed, not how output is rendered.  It's not kin
to other space escapes like \~ or \|, as the original term implied.

I've certainly quibbled with some of his specific changes, and you
raise good points about the organization of this particular passage.
But overall I find his rewrites make the documentation stronger than
what came before.

I also appreciate that he's putting so much energy into a package
whose development seemed moribund for a couple years after Werner
stepped back.  It would be great if we had MORE people actively
working on the documentation, so that we'd have other viewpoints
represented, perhaps reining in quirks like Branden's overreliance on
footnotes.  But ultimately the metric for successful editing of prose
isn't "is the end result perfect?" but "is the end result better than
how it started?"  By that standard I find Branden's work on the groff
documentation a smashing success.