Hacker News Reader

Comment by classified | Hacker News Reader

This is helpful to get all doc authors to use the same vocabulary. One ambiguous wording that I keep seeing is "X may not do Y". Does the author mean that X possibly doesn't do Y or do they mean it's strictly forbidden that X do Y (-> "x MUST NOT do y")?

View on HN

Clearly what we need is for documentation to embrace the subtlety that can only be expressed by a double or even triple modal auxiliary: "when the server receives a request, it'll might could reply with either a standard response or an error code... unless it entirely fails, in which case it might not would do anything; the client may oughta detect this with a timeout, but may can instead wait for the operator to intervene and explicitly cancel the operation".

As outlined in Dr. Dan Streetmentioner’s Software Developer’s Handbook of 1001 Tense Formations

In the author means that X possibly doesn't do Y, and possibly does do Y, then I'd say just drop the "not". "X may do Y".

I'd use these:

X shall Y: X always does Y.

X shall not Y: X never does Y.

X should Y: it is expected that X will do Y, but it might not often enough that this case needs to be handled (as opposed to an "X shall Y" not doing Y which would be considered to total failure of the system).

X should not Y: it is expected that X will not do Y, but if it does you should handle it.

X may Y: both X does Y and X does not do Y are OK.

To me, that reads as 'X is not allowed to do Y' without any ambiguity until you pointed it out and I thought hard about it.

Wondering whether that is common response or not.

it's an ambiguous parse for sure, but the meaning is usually clear in context. it's possible to create a really ambiguous example though, e.g. "when pinged, the server may not respond". is this stating a requirement that the server never responds to pings, or is it a warning that the server doesn't always respond?

The problem is statement vs command.

"X may not do Y." as a statement implies that X doing Y is unusual, but possible.

"X may not do Y." as a command implies that X doing Y is a mistake.

A technical document must not include the term "may not". "Must not" or "might not".

Reply on news.ycombinator.com