Technical specs and docs
Technical specs: MUST is not SHOULD
In a specification, one capitalized word separates a requirement from a recommendation, and “at least once” promises something very different from “exactly once”. LexyRead helps you read them as written.
Try it on your own text
Three lines to try
Read each line. Before you open it, decide which word changes the meaning.
-
Clients MUST NOT retry a request that returned 409.
Check my reading
The deciding wordsClients MUST NOT retry a request that returned 409.
Easy to read asClients should try not to retry a 409.
What it actually saysRetrying a request that returned 409 is not allowed. A client that does it does not follow the spec.
Without “NOT”, retrying would be required.
-
Servers SHOULD cache responses for 60 seconds.
Check my reading
The deciding wordsServers SHOULD cache responses for 60 seconds.
Easy to read asServers must cache responses for 60 seconds.
What it actually saysCaching is recommended. A server can skip it for a good reason and still follow the spec.
Change “SHOULD” to “MUST” and a server that skips the cache would break the spec.
-
Messages are delivered at least once.
Check my reading
The deciding wordsMessages are delivered at least once.
Easy to read asEach message arrives exactly once.
What it actually saysEvery message arrives, and some may arrive more than once. Your code has to handle duplicates.
Change it to “at most once” and messages could be lost but never repeated.
How LexyRead helps
Bring your own text
Paste or upload the document you actually have to read.
Find the word first
You pick the word you think decides the meaning before anything is shown.
Check against the exact words
LexyRead marks a word only when changing it would change the meaning, and shows the line it comes from.
LexyRead is reading practice. Always check the specification itself before you ship.
Try it on your own text
LexyRead keeps the original text in front of you. It does not summarize it.
Try it on your own text