Re: Documentation evolution

[Dave Kemper]

On 5/6/22, Ralph Corderoy <ralph@inputplus.co.uk> wrote:
> And I think it is wrong to make this change.  ‘\&’ has always been known
> as the escape for a zero-width space.  Other documentation has and will
> continue to refer to it as ZWS so the rename has just added confusion.

That situation isn't ideal, but the alternative is to be forever
beholden to whatever terms someone came up with 50 years ago, even if
more accurate alternatives exist.  That stymies progress.

Backward compatibility in groff has always been a prime consideration,
but even in the behavior of the language, small things have changed
over the decades.  Such changes are not made capriciously and always
seem to give due consideration to their effect on historical roff
documents.  In documentation we can be a little freer, especially with
modern search capabilities: someone looking at older documentation
that uses the term "zero-width space" can see that term applies to the
escape \&, and, not finding any such term in the current docs, search
for \& itself to find what they need.  (This would be less true of
what is now termed the output comparison operator, since it has no
fixed delimiter to search for -- except that operator seemed to have
no name in historical docs.)

> One key thing in technical documentation is to be consistent over terms.

Many of Branden's edits have improved exactly that.  Reading the
commit logs for documentation files, and seeing the number of times
this sort of change comes up, it's kind of astonishing how
inconsistent the terminology was before.

> ‘\&’ can be thought of in the output sense as, say, sitting after an
> end-of-sentence character so it loses that quality.

Perhaps for that particular usage, but it has others, and in the
general sense, it always affects input parsing.

> Let's assume it's now more accurate and delves into more corners.  That
> would be good but not if the volume and style puts off readers compared
> to before.

True.  I wonder if that's the case, though.  Does anyone else find the
current style off-putting?  I know usability of the documentation is a
key consideration for Branden, and while I of course can't speak for
him, I'm fairly confident that if multiple people voiced concerns with
some aspects of it, he'd make refinements taking that feedback into
account.

Sorry that lawyers prevent you from contributing directly to the code
and docs.  More voices, especially ones coming at things from
differing viewpoints, only strengthen the end product.