On 5/2/22, Ralph Corderoy <ra...@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.
