RE: Scan of regexps in Emacs (March 17)

[Drew Adams <drew.adams@oracle.com>]

> > As the Emacs documentation currently has thousands of occurrences of
> > "should", it sounds like we don't generally follow the guideline you're
> > suggesting.

If they're accompanied by stating _why_ you should
then there's generally no problem understanding.

Call that a scoped/qualified "should" - not really
a problem, because the follow-up explains (by
describing consequences) what we mean there by
"should".
 
> Indeed.  And the reason is likely that our documentation is not
> "technical documentation" in the sense meant in that article.

There was no article.  Just my opinion.  (The URL
was just to explain the term "weasel word".)

And in my opinion our doc _is_ technical doc.

If we don't say why you should then it's usually
preferable (IMO) to say that we "recommend" that
you do XYZ than to say you "should" do XYZ.

In any case, it's usually helpful to say why.

The problem with an empty "should" is that it's
vague, and it can be misunderstood as a (possibly
shame-faced) "must".  (Shame-faced ~ weasel.)

Something that's presented as an unexplained
recommendation is at least seldom confused with a
requirement (a "must").  "Should" is more vague
and is often understood as stronger than just
"it's a good idea" (a recommendation).

But "should", "recommend", and "must" all typically
beg the question of what happens if you don't.
With "should", in particular, it's also typically
unclear how important it is that you do what's
suggested.

"Must" is pretty clearly important - a requirement
of some sort.  But for "must" too it helps to say
what happens if you don't respect the rule.

To be clear, I'm not saying it's appropriate or
enough to just replace all occurrences of "should",
or that all such occurrences are unwise.