Modal Verbs in Technical Writing: Must, Should, May, Might

Modal verbs are small words that carry enormous weight in technical writing. The difference between “you must restart the server” and “you should restart the server” is the difference between a mandatory instruction and a recommendation. Choosing the wrong modal can create security vulnerabilities, legal problems, or simply confuse the reader about what is actually required.

This guide explains the six most important modal verbs for technical writing, with special attention to the RFC 2119 standard used in specifications, API documentation, and system design documents.

In everyday conversation, modals are often interchangeable. In technical writing, they are not:

Must → non-negotiable requirement; failure means the system will not work or is insecure
Should → strong recommendation; valid reasons to deviate may exist
May → optional; permitted but not required
Might → possibility in the future or under certain conditions

Getting these right is not just about grammar — it is about communicating the intended level of compliance to the reader.

RFC 2119: The Technical Writing Standard

RFC 2119 defines keyword definitions for IETF standards documents. They are widely adopted beyond IETF — API documentation, internal technical specs, and design documents use the same conventions.

When a document explicitly references RFC 2119, these keywords are written in ALL CAPS:

“The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.”

MUST / MUST NOT (Required)

MUST indicates an absolute requirement. Non-compliance means the implementation is broken, non-conformant, or insecure.

Context	Example
API requirement	”Every request MUST include a valid Authorization header.”
Security	”Passwords MUST be hashed using bcrypt or Argon2 before storage.”
Protocol	”The client MUST close the connection if it receives a 401 response.”
Configuration	”The `database_url` field MUST be set before starting the application.”

MUST NOT prohibits an action absolutely:

“Clients MUST NOT retry requests that return a 422 status code without first correcting the invalid parameters.”

“API tokens MUST NOT be included in URL query parameters — they MUST be passed in the Authorization header.”

Lowercase equivalent: “must” / “required”

In prose documentation (not formal specifications), lowercase “must” carries the same mandatory meaning:

“Users must verify their email address before accessing premium features.”

SHOULD / SHOULD NOT (Recommended)

SHOULD means the described behaviour is strongly recommended, but valid reasons exist to deviate in specific circumstances. A developer may choose not to follow a SHOULD requirement, but must understand the implications.

Context	Example
Performance	”Clients SHOULD implement exponential backoff for 429 responses.”
Error handling	”Services SHOULD return a correlation ID in every error response.”
API design	”Endpoints SHOULD use plural nouns: /users, /orders.”
Security	”Applications SHOULD enforce HTTPS redirects at the load balancer layer.”

SHOULD NOT indicates something that is not recommended but is not forbidden:

“Responses SHOULD NOT exceed 1MB in size unless the client explicitly requests a larger payload.”

The “SHOULD trap”

The most common mistake: using SHOULD when you mean MUST.

If a developer ignores the SHOULD instruction and the system breaks, fails security review, or causes incorrect behaviour — you should have written MUST.

“The Content-Type header SHOULD be application/json.”

If a request without this header will fail, this should be MUST. Reserve SHOULD for cases where deviation has a cost but is sometimes justified.

MAY / OPTIONAL (Permitted)

MAY indicates that behaviour or a feature is completely optional. The caller or implementation may choose to include it or not, with no obligation.

“The metadata field MAY contain any valid JSON object with additional context.”

“Clients MAY cache responses for up to 5 minutes using the value in the Cache-Control header.”

“The include_archived parameter is OPTIONAL. When omitted, archived items are excluded by default.”

MAY vs CAN

MAY = is permitted to (granting permission)
CAN = is able to (technical capability)

❌ “The server can return a 303 redirect.” (does this mean it is permitted, or that it has the technical ability?) ✅ “The server MAY return a 303 redirect to an alternate resource.” (clearly permitted, not required)

MIGHT (Possibility)

Unlike the RFC-defined modals, might is used in technical prose to describe uncertain or conditional outcomes, not requirements.

“The request might time out under high server load.” “Clearing the cache might cause elevated database load for 1–2 minutes.” “Memory usage might spike during the initial indexing process.”

Might vs may in technical writing:

“The process might fail” → there is a chance of failure (possibility)
“Clients may retry the request” → clients are permitted to retry (permission)

WILL vs SHALL vs MUST

Word	Usage
will	Describing guaranteed behaviour: “The API will return a 200 status on success.”
shall	Formal synonym for MUST (older spec style, less common now): “The server shall validate the token signature.”
must	Current preference for mandatory requirements

In modern technical writing, prefer will for describing system behaviour and must for imposing requirements.

“If the token is expired, the server will return 401. Clients must request a new token using the refresh endpoint.”

Practical Examples by Document Type

API Documentation

## Authentication

All API requests MUST be authenticated using a Bearer token.

Include the token in the Authorization header:
Authorization: Bearer YOUR_TOKEN

Tokens MUST NOT be embedded in the request URL.

Expired tokens will return a 401 Unauthorized response. 
Clients SHOULD implement automatic token refresh using the 
/auth/refresh endpoint.

Runbook

## Deployment Checklist

Before deploying:
- You must notify the on-call engineer at least 30 minutes before.
- You should verify the staging environment is healthy.
- You may skip the staging verification for hotfixes, but must document the reason.

During deployment:
- You must monitor the error rate for 10 minutes after the rollout.
- If error rate exceeds 1%, you must immediately initiate a rollback.

Architecture Decision Record

## Decision

All inter-service communication MUST use mTLS for authentication. 
Plain HTTP between services in the internal network MUST NOT be permitted.

Services SHOULD use gRPC where low-latency bidirectional streaming is 
required. REST over HTTPS MAY be used for synchronous request-response 
calls where gRPC integration overhead is not justified.

Common Mistakes

1. Overusing MUST

Not everything is mandatory. Using MUST for recommendations weakens all your other MUST statements.

❌ “Developers MUST follow the style guide for commit messages.” ✅ “Developers SHOULD follow the style guide for commit messages.” (unless non-compliance blocks CI — then MUST)

2. Using SHOULD when you mean MUST

As described above: if deviation breaks the system or creates a security issue, use MUST.

3. Mixing RFC 2119 language with casual language

Inconsistently mixing formal MUST/SHOULD with casual “please make sure” or “it’s recommended that” confuses readers about the compliance level.

4. Passive constructions that hide the actor

❌ “It must be ensured that the timeout is configured.” ✅ “The operator must configure the timeout before deployment.”

The second version is unambiguous about who is responsible.

5. Using “need to” as a MUST synonym

“You need to authenticate” sounds mandatory but is weaker than “You must authenticate” in technical writing — it is also conversational and variable in meaning.

Quick Reference Card

Modal	Obligation	Example
MUST	Absolute requirement	”Requests MUST include an API key.”
MUST NOT	Absolute prohibition	”Tokens MUST NOT be stored in localStorage.”
SHOULD	Strong recommendation	”Clients SHOULD retry on 503 with backoff.”
SHOULD NOT	Not recommended	”Responses SHOULD NOT exceed 10MB.”
MAY / OPTIONAL	Permitted, not required	”The `lang` parameter MAY be included.”
will	Guaranteed behaviour	”The server will return 200 on success.”
might	Uncertain possibility	”The process might take up to 5 minutes.”
can	Technical capability	”The CLI can output JSON with —format=json.”

Practice Exercises

Rewrite each sentence using the correct modal verb:

“It’s recommended that you use HTTPS for all API calls.”
“You definitely have to close the database connection when done.”
“It’s possible to add a fields parameter to filter the response.”
“You need to include a request body for POST requests.”
“The cache might sometimes contain stale data after updates.”

Suggested answers:

“Clients SHOULD use HTTPS for all API calls.”
“The application must close the database connection when done.” (or MUST)
“Clients MAY add a fields parameter to filter the response.”
“POST requests MUST include a request body.”
Correct as-is — “might” is appropriate for uncertainty.

Why Modal Verbs Matter in Technical Writing