Tense and mood

Tense locates an action in time, and mood distinguishes statements from commands and hypothetical conditions. Use this page when choosing the verb form for a product behavior, condition, or instruction.

Present tense by default

tense-001 should GuidesAPI docsMarketingBlog

Use present tense as the default for all technical and product documentation.

Examples

• ✓ The API returns a JSON object.
• ✗ The API will return a JSON object.

Rationale

Present tense states product behavior as generally true and keeps the description direct.

Future tense only for later events

tense-002 should GuidesAPI docsMarketingBlog

Use future tense, will, only when an action occurs at a later point in time or asynchronously. Don’t use it as a stylistic default.

Examples

• ✓ Clicking Save updates the record.
• ✗ Clicking Save will update the record.
• ✓ The export will be available when processing finishes.

Rationale

When will appears only for later or asynchronous events, it tells the reader that the timing matters. Used everywhere, it tells them nothing.

Avoid the hypothetical “would”

tense-003 should GuidesAPI docsMarketingBlog

Avoid the hypothetical future would in technical documentation.

Examples

• ✓ If you omit the header, the request fails.
• ✗ If you omit the header, the request would fail.

Rationale

In a product-behavior description, would can make a known outcome sound speculative. A present-tense conditional states what happens.

Indicative mood for statements

tense-004 should GuidesAPI docsMarketingBlog

Use the indicative mood as the default for statements, facts, explanations, and assertions.

Examples

• ✓ The SDK caches responses for 5 minutes.
• ✗ Understand that the SDK caches responses for 5 minutes.

Rationale

The indicative presents behavior as fact. Wrapping the statement in an instruction such as understand that or note that adds words and turns a fact into a task.

Imperative mood for instructions

tense-005 should GuidesAPI docsMarketingBlog

Use the imperative mood for instructions, procedures, and direct commands. The implied you makes explicit address unnecessary in procedural steps.

Examples

• ✓ 1. Open the settings file.
• ✗ 1. You need to open the settings file.

Rationale

The imperative names the action first and keeps procedural steps parallel. Because the subject is understood, repeating you needlessly lengthens each step. It also translates cleanly: a step with no subject spares the translator a choice of pronoun, formality, and gender.

Avoid the subjunctive

tense-006 should GuidesAPI docsMarketingBlog

Avoid the subjunctive mood in technical documentation.

Examples

• ✓ If the token is expired, the request fails with a 401.
• ✗ If the token were expired, the request would fail with a 401.

Rationale

The subjunctive can make a condition the product handles sound like one that never happens. A condition that occurs at run time is real, so the indicative conditional fits it.

Don’t switch moods mid-sentence

tense-007 should GuidesAPI docsMarketingBlog

Don’t switch moods within a single sentence.

Examples

• ✓ Click Save to commit the file.
• ✗ Click Save and the file is committed.

Rationale

A switch from imperative to indicative joins a reader action and a product result as if both were things the reader does. In one mood, the sentence says which is the action and which is the result.

Avoid ambiguous -ing words

tense-008 should GuidesAPI docsMarketingBlog

When you use an -ing word, make clear whether it is a verb, noun, or adjective, especially in headings (head-007).

Examples

• ✓ ## Monitor services
• ✗ ## Monitoring services

Rationale

Monitoring services can mean the activity of monitoring services or services that perform monitoring. A heading has no surrounding sentence to settle the meaning.