Skip to content

RFC 2119 Keywords for Prescriptive Tone

Context

Documentation that mixes recommendation strength is ambiguous and unactionable. A sentence such as "you should use a structured logger" can be read as "we mandate it", "we prefer it", or "we'd consider it nice". The reader's interpretation depends on their training, their team, and their guess about the author's intent. For a prescriptive guide whose explicit purpose is to remove ambiguity from technology choices, that variance is intolerable.

RFC 2119 (and its 2017 clarification RFC 8174) defines five capitalised keywords — MUST, MUST NOT, SHOULD, SHOULD NOT, MAY — with precise, testable meanings. These keywords are the IETF and W3C standard for specification prose and are universally understood by engineers and by LLM agents trained on standards documents. Adopting them throughout the guide gives every prescriptive sentence a single unambiguous reading: a MUST is a non-negotiable invariant; a SHOULD is a default that MAY be overridden with documented justification; a MAY is permissive optionality.

The alternatives considered include lowercase plain prose ("you should use X"), bespoke severity tags such as "P0 / P1 / P2", and informal "recommended / optional" labels. Each was rejected because none has the combination of (a) standardised meaning, (b) reader familiarity, (c) machine-checkability, and (d) cultural fit with the engineering audience that RFC 2119 keywords have.

Decision Drivers

  • Every prescriptive sentence MUST have an unambiguous strength reading for human readers and LLM agents alike.
  • The convention MUST be checkable by simple text search ("does this prescription contain MUST / SHOULD / MAY?").
  • The convention SHOULD already be familiar to the engineering audience so that no in-house glossary is required for fluent reading.
  • The convention SHOULD survive translation and paraphrase by LLM agents that index the guide.
  • The convention MUST scale across chapters, ADRs, and the Reference Implementation admonitions without per-section divergence.

Considered Options

  • RFC 2119 capitalised keywords (MUST / MUST NOT / SHOULD / SHOULD NOT / MAY) throughout
  • Plain prose ("you should", "we recommend", "it's best to")
  • Bespoke severity tags (P0 / P1 / P2, or red / amber / green)
  • Informal labels ("Recommended", "Optional", "Avoid") as section-level tags only

Decision Outcome

Chosen option: "RFC 2119 capitalised keywords throughout", because it is the only option that satisfies every decision driver simultaneously. The keywords are standardised, familiar to engineers, machine-checkable, and survive paraphrase: an LLM agent that ingests the guide will preserve "MUST" / "SHOULD" / "MAY" verbatim in its responses. The Introduction chapter MUST contain a section defining the keywords with the canonical RFC 2119 / RFC 8174 boilerplate so that readers unfamiliar with the convention can decode it without leaving the guide.

Positive Consequences

  • Readers MAY scan a chapter for MUST to find non-negotiable invariants.
  • CI MAY (in a future workflow) grep for unkeyworded prescriptive verbs ("should", "must" lowercase) and warn on them.
  • LLM agents MAY ground their responses by quoting the surrounding MUST / SHOULD / MAY clause verbatim.

Negative Consequences

  • Authors MUST think about strength every time they write a prescriptive sentence — this is an editorial overhead, not a free convention.
  • Prose can feel formal or stilted to readers unfamiliar with the IETF convention; the Introduction chapter MUST onboard them.

Consequences

After this decision, every prescriptive sentence in every chapter and every ADR MUST use one of MUST / MUST NOT / SHOULD / SHOULD NOT / MAY, capitalised. Non-prescriptive prose (context, motivation, examples) is exempt. The Introduction chapter MUST contain a section explicitly defining the keywords per RFC 2119 / RFC 8174. Authors SHOULD review their prose for lowercase "should" and "must" usages and either capitalise them (if prescriptive) or rephrase (if descriptive).

Pros and Cons of the Options

RFC 2119 capitalised keywords throughout

The IETF / W3C standard convention for specification prose.

  • Good, because the keywords have standardised, testable meanings.
  • Good, because the engineering audience already knows them.
  • Good, because the keywords survive LLM paraphrase verbatim.
  • Bad, because authors MUST decide strength explicitly for every prescriptive sentence.

Plain prose ("you should", "we recommend")

Standard descriptive English without capitalised keyword markers.

  • Good, because the prose reads more naturally to non-spec audiences.
  • Bad, because strength is ambiguous — "should" can mean "must" or "may" depending on context.
  • Bad, because LLM agents lose strength information when paraphrasing.

Bespoke severity tags (P0 / P1 / P2)

In-house labels with documented severity meanings.

  • Good, because severity is explicit per sentence or paragraph.
  • Bad, because every reader and every adopting org MUST learn the bespoke vocabulary.
  • Bad, because severity-of-recommendation does not map cleanly onto incident-severity tag conventions, causing confusion.

Section-level annotations without sentence-level keywords.

  • Good, because authors MAY annotate whole sections cheaply.
  • Bad, because individual prescriptive sentences within a section MAY still have varying strength, which the section-level tag cannot express.