tense-001 should GuidesAPI docsMarketingBlog Use present tense as the default for all technical and product documentation.
Tense and mood
Documentation describes current behavior, so it lives in the present tense and the indicative mood, switching to the imperative for instructions. These rules cover the defaults and the constructions to avoid.
Present tense by default
Section titled “Present tense by default”Examples
- ✓ The API returns a JSON object.
- ✗ The API will return a JSON object.
Rationale
Documentation describes how the product behaves now, so present tense states that behavior directly.
Future tense only for later events
Section titled “Future tense only for later events”tense-002 should GuidesAPI docsMarketingBlog Use future tense (‘will’) only when an action genuinely occurs at a later point in time or asynchronously; do not use it as a stylistic default.
Examples
- ✓ Clicking Save updates the record.
- ✗ Clicking Save will update the record.
- ✓ The v1 endpoint will shut down on June 30.
Rationale
Reserving “will” for genuinely later or asynchronous events keeps it meaningful instead of a habit.
Avoid the hypothetical “would”
Section titled “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
“Would” introduces a conditional that is usually vaguer than a plain present-tense statement of behavior.
Indicative mood for statements
Section titled “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 five minutes.
- ✗ Understand that the SDK caches responses for five minutes.
Imperative mood for instructions
Section titled “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 puts the reader in the driver’s seat and drops the redundant “you” in each step.
Avoid the subjunctive
Section titled “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 suits counterfactuals, which are rare in documentation; the indicative conditional fits real runtime conditions.
Don’t switch moods mid-sentence
Section titled “Don’t switch moods mid-sentence”tense-007 should GuidesAPI docsMarketingBlog Do not switch moods within a single sentence.
Examples
- ✓ Click Save to commit the file.
- ✗ Click Save and the file is committed.
Rationale
Switching from an instruction to a statement mid-sentence makes the actor incoherent.
Watch ambiguous -ing words
Section titled “Watch ambiguous -ing words”tense-008 should GuidesAPI docsMarketingBlog Use ‘-ing’ words carefully and ensure their grammatical role (verb, noun, or adjective) is unambiguous from context, especially in headings.
Examples
- ✓ ## Schedule a report
- ✗ ## Scheduling reports
Rationale
An -ing word can be a verb, noun, or adjective, so unclear use blurs whether it names an action or a thing, especially in headings.