This reference article consolidates the tense and person (first, second, third) decisions covered throughout this style guide. Use it as a quick lookup when you are unsure how to handle a specific writing situation.
Source articles: this table summarizes guidance drawn from the Verbs, Tense, and Mood guide (tense and modal verbs) and the Point of View section of the Common Voice and Tone Mistakes guide (person). Where a row here doesn't cover a nuance you need, check the source article — this reference is meant for fast lookup, not as a replacement for the fuller reasoning.
Person
| Person | Use when | Example |
|---|---|---|
| Second person (you, your) | Addressing the reader in procedural and conceptual content — the default for most documentation | "You can configure this setting in the Users panel." "Your account is now set up." |
| First person plural (we, our) | Referring to your organization — use sparingly | "We recommend backing up your data before migrating." Avoid overusing "we" — it can feel like a sales voice rather than a documentation voice. |
| Third person (they, the user, the administrator) | When writing about a different party's action in relation to the reader — typically in reference documentation, or describing what one role does that affects another | "When a reader submits feedback, the administrator receives a notification." "They can edit the article from the sidebar." |
| First person singular (I, my) | Almost never in documentation | Avoid entirely except in quoted examples or user-facing error messages where the product speaks in first person. |
A note on third person: third person is correct when the article is genuinely describing someone other than the reader — for example, an administrator's action that affects the reader, in a piece written for the reader. It is not correct as a generic stand-in for the reader themselves. "The administrator receives a notification" is fine in an article written for readers who aren't the administrator. "Users can access this feature" is not fine in an article written directly for the user doing the accessing — that should be "You can access this feature." If the reader IS the person being described, use second person, not a third-person label for their own role.
Whichever person you choose for an article, use it consistently throughout — see the Point of View section of the Voice and Tone guide for the full rule against drifting between forms mid-article.
Tense
| Tense | Use when | Example |
|---|---|---|
| Simple present | Describing how things work — the default tense for most documentation | "The dashboard displays your five most recent articles." "The system validates the entry when you click Submit." |
| Imperative (present) | Instructional steps — any time you are telling the reader to take an action | "Click Save." "Enter your email address." "Go to Settings." |
| Present progressive (is/are + -ing) | Describing a process currently in progress, usually as part of describing what happens during a step | "The file is uploading." "The system is processing your request." |
| Simple past | Release notes and changelogs; historical context | "Fixed an issue where the export button was unresponsive." "Added support for CSV imports." |
| Future (will) | Describing the result of an action in sequential instructional content — acceptable but use sparingly | "Click Submit. A confirmation email will be sent to your address." Prefer present tense when possible: "A confirmation email is sent to your address." |
| Conditional (if/when + present) | Describing what happens under a specific condition | "If you leave the field blank, an error message appears." "When you save, the record updates automatically." |
Modal Verbs Quick Reference
| Modal | Meaning in documentation | Example |
|---|---|---|
| can | This is possible or permitted | "You can export up to 10,000 records at a time." |
| cannot | This is not possible or not permitted | "You cannot delete your own account." |
| must | This is required — skipping it will cause a problem | "You must verify your email before logging in." |
| should | This is recommended — skipping it is possible but not advised. Do not use "should" when the action is actually required; if skipping it causes an error, data loss, or failure, use "must" instead. | "You should save your work before closing the editor." |
| may | This might happen — genuine uncertainty | "Processing may take several minutes depending on file size." |
| will | This will happen — a predictable result | "Clicking Delete will remove the article permanently." |
Note: "might" and "could" are deliberately excluded from this table — the Modal Verbs section of the Verbs, Tense, and Mood guide recommends avoiding both in most documentation contexts, since they imply more uncertainty than usually exists. Use "may" for genuine uncertainty instead.
Common Person and Tense Errors
| Error | Correct form |
|---|---|
| Users can access this feature... (third person as a stand-in for the reader) | You can access this feature... |
| One should ensure the field is completed. (impersonal first person singular) | Make sure the field is completed. (imperative) |
| The article will be saved when the button is clicked. (passive future) | Click Save to save the article. (active imperative) |
| We are excited to announce that you can now export to PDF. (marketing voice) | You can now export articles to PDF. (direct, factual) |
| This feature allows users to upload files. (weak "allows" construction, distancing the reader in third person) | Use this feature to upload files. or: You can upload files using this feature. |
Using This Reference
- Confirm the person and tense chosen for a sentence match what's used consistently across the rest of the article.
- If third person is used, confirm it describes someone other than the reader — not a generic stand-in for the reader's own role.
- If "should" appears, confirm the action is genuinely optional and not actually required.
- If "might" or "could" appears, replace with "may" or a direct statement of the actual variability.
- For anything not resolved by this table, check the source articles listed above rather than guessing.