Grammar for Writing Technical Requirements

Requirements documents are one of the most grammar-sensitive genres in software engineering. A poorly worded requirement does not just read badly — it creates ambiguity that can lead to the wrong thing being built, contract disputes, and failed acceptance tests. Understanding the grammar patterns that produce precise, unambiguous requirements is a practical engineering skill.

This guide covers the key grammatical choices in requirements writing: verb tenses, modal verbs, and/or logic, voice, and list formatting.

Present Simple vs. Shall

The present simple for system behaviour

When describing what a system does — its normal behaviour — use the present simple tense. This is the standard in functional requirements.

• “The system validates the user’s email address before account creation.”
• “The API returns a 404 status code when the requested resource does not exist.”
• “The payment service sends a confirmation email within 30 seconds of a successful transaction.”

The present simple describes a timeless truth about the system — not what it will do in the future, or what it did in the past, but what it does as a matter of its defined behaviour.

Shall for obligations (legacy style)

Older requirements documents, especially in government, defence, and regulated industries, use “shall” to express mandatory requirements:

• “The system shall authenticate users via OAuth 2.0.”
• “The application shall store passwords as salted hashes using bcrypt.”

“Shall” in this context means “is required to” — it is not a future tense marker but an obligation marker. If you encounter this convention in your organisation, use it consistently. If you are starting fresh, the modern RFC 2119 convention of writing MUST (in uppercase) is clearer.

Mixing tenses: a common mistake

Mixing present simple with future simple (“will”) in the same document creates confusion about whether you are describing current behaviour or future behaviour.

• Ambiguous: “The system validates the input. It will return an error if the input is invalid.”
• Clear: “The system validates the input. It returns an error if the input is invalid.”

Use “will” only when you explicitly need to indicate a future change or a response to a trigger event: “After the user clicks Submit, the system will display a loading indicator.” Even here, present simple is often cleaner: “After the user clicks Submit, the system displays a loading indicator.”

Avoiding Ambiguity with “And” / “Or”

“And” and “or” are among the most dangerous words in requirements documents because their logical meaning is often ambiguous in natural English. Legal and technical writing has specific conventions for eliminating this ambiguity.

The ambiguity problem

“The system accepts VISA, Mastercard, and Amex” — does this mean the system must accept all three, or that it accepts at least one of the three? In English prose, this reads as “all three” because of the serial comma. That is fine.

But consider: “Users must provide a valid email address and phone number or a government-issued ID.” Does this mean:

• (email AND phone) OR (government ID)
• email AND (phone OR government ID)

This is genuinely ambiguous. A developer and a product manager reading this sentence could implement entirely different logic.

How to resolve it

Option 1: Rewrite to eliminate the conjunction.

Instead of: “Users must provide a valid email address and phone number or a government-issued ID.”

Write: “Users must provide either (a) a valid email address and a valid phone number, or (b) a government-issued ID.”

Option 2: Use numbered sub-requirements.

The user must provide at least one of the following to verify their identity:
1. A valid email address AND a valid phone number
2. A government-issued ID

Option 3: Use “and/or” explicitly.

“The system logs errors and/or warnings to the monitoring service.” — This explicitly means one, the other, or both.

However, “and/or” is not a substitute for thinking clearly. Use it only when both cases genuinely apply.

”Either…or” vs. “both…and”

• “The system accepts either an API key or a bearer token.” — one or the other, not both
• “The request must include both the user ID and the session token.” — both required

Using these structures explicitly removes ambiguity from conjunction-heavy requirements.

Active vs. Passive Voice in Specifications

When to use active voice

Active voice names the subject performing the action. In requirements, the subject is usually “the system,” “the user,” or a specific component.

• “The system validates the token on every request.”
• “The user selects a payment method from the dropdown.”
• “The API gateway authenticates the request before routing it to the backend service.”

Active voice is clearer about responsibility. It makes it obvious which component must do what.

When passive voice is appropriate

Passive voice is acceptable in requirements when the actor is unknown, irrelevant, or when the receiver of the action is the focus.

• “Passwords are stored as bcrypt hashes.” — the focus is on the storage format, not on which component stores them
• “Log entries are retained for 90 days.” — the retention policy is the requirement; the mechanism is secondary
• “Failed login attempts are recorded in the audit log.” — acceptable if the responsibility for recording is established elsewhere

The passive voice trap

Passive voice in requirements can hide responsibility and create disputes about who is responsible for implementing a requirement.

• Ambiguous: “The session is terminated after 30 minutes of inactivity.” — which component terminates it?
• Clear: “The session management service terminates the session after 30 minutes of user inactivity.”

If there is any chance of ambiguity about responsibility, use active voice and name the responsible component explicitly.

Numbered Lists for Precision

Prose requirements are harder to reference, test against, and audit than structured lists. Using numbered lists converts a paragraph of requirements into testable, referenceable items.

Before: prose requirements

“The registration form should validate that the email address is in a valid format, that the password is at least eight characters long and contains at least one uppercase letter, one lowercase letter, and one number, and that the user has agreed to the terms of service.”

This contains at least five separate requirements packed into one sentence. It is difficult to test, difficult to reference in a bug report (“failing requirement three”), and easy to miss partially.

After: numbered list requirements

The registration form MUST validate all of the following before submission:

1. The email address conforms to RFC 5321 format.
2. The password is at least 8 characters in length.
3. The password contains at least one uppercase letter (A–Z).
4. The password contains at least one lowercase letter (a–z).
5. The password contains at least one numeric digit (0–9).
6. The user has checked the "I agree to the Terms of Service" checkbox.

Now each requirement is independently testable. A failing acceptance test can reference “requirement 4” precisely. A code reviewer can check each item in isolation.

Hierarchical requirements

For complex systems, use hierarchical numbering:

3. Authentication Requirements
   3.1 The system MUST support OAuth 2.0 authentication.
   3.2 The system MUST support API key authentication for service-to-service calls.
   3.3 The system SHOULD support SAML 2.0 for enterprise customers.
      3.3.1 SAML metadata MUST be configurable per tenant.
      3.3.2 The system MUST support both IdP-initiated and SP-initiated flows.

This structure makes the requirements navigable, traceable, and auditable.

A Grammar Checklist for Requirements Documents

Before sending or publishing a requirements document, run through this checklist:

• All mandatory requirements use MUST or “shall” consistently
• All recommended but optional requirements use SHOULD or MAY
• No “and/or” constructions where the intent is unclear
• Complex conjunctions are resolved with numbered alternatives
• Active voice is used wherever a specific component is responsible
• Requirements are numbered and independently testable
• Tense is consistent throughout (present simple for system behaviour)

Precision in requirements grammar is not pedantry — it is the difference between a feature built correctly and a feature built to the wrong specification.