person-001 should GuidesAPI docsMarketing Address the reader in the second person, you and your, by default throughout documentation.
Person and point of view
Point of view determines how documentation refers to the reader, the authoring organization, the software, and its end users. This guide uses you for the reader and third person for software and end users, with narrow uses for we and I. Use this page when a sentence doesn’t clearly identify who acts.
Address the reader as “you”
Section titled “Address the reader as “you””Examples
- ✓ You can configure the timeout in
config.yml. - ✗ Users can configure the timeout in
config.yml.
Rationale
Second person makes clear that an action or choice belongs to the reader in both instructions and reference content.
Rewrite around singular “they”
Section titled “Rewrite around singular “they””person-002 should GuidesAPI docsMarketingBlog As an alternative to singular they, rewrite the sentence with a plural noun or omit the pronoun.
Examples
- ✓ Developers can restrict their tokens to a single project.
- ✓ Each developer can restrict the token to a single project.
Rationale
Where singular they is awkward, or a reader could take it as a plural, a plural noun or no pronoun keeps the sentence clear without a gendered pronoun.
Reserve “user” for end users
Section titled “Reserve “user” for end users”person-003 should GuidesAPI docsMarketingBlog Reserve user for the end user of the software you’re documenting. Don’t use it as a synonym for the reader of the documentation.
Examples
- ✓ You can find the full parameter list in the appendix.
- ✗ The user can find the full parameter list in the appendix.
Rationale
Using user for both the reader and the software’s end user makes it harder to tell which one a sentence means.
Use third person for software and end users
Section titled “Use third person for software and end users”person-004 should GuidesAPI docsMarketingBlog Use third person for actions performed by software or by end users. Reserve second person for what the reader does.
Examples
- ✓ When the user selects a plan, the app calls the
subscribeendpoint. - ✗ When you select a plan, the app calls the
subscribeendpoint.
Rationale
Using you consistently for the reader distinguishes instructions from descriptions of what the software or an end user does.
Limit “we” to the organization
Section titled “Limit “we” to the organization”person-005 should GuidesAPI docsMarketingBlog Use first-person plural, we, our, and us, only for the authoring organization, and make the reference unambiguous. Prefer rephrasing to avoid it, and don’t use it to mean the reader and writer together.
Examples
- ✓ In this tutorial, you set up the client and send your first request.
- ✗ In this tutorial, we set up the client and send our first request.
Rationale
Without a clear reference, we can mean the organization, the writer, or the writer and reader together.
Restrict “I” to UI text and FAQs
Section titled “Restrict “I” to UI text and FAQs”person-006 should GuidesAPI docsMarketingBlog Use first-person singular, I and me, only in UI text written from the user’s point of view, such as checkbox labels, and in FAQ questions. Avoid it in body text.
Examples
- ✓ Enable rate limiting to protect your endpoints.
- ✗ I recommend enabling rate limiting to protect your endpoints.
Rationale
A checkbox label or an FAQ question speaks as the user, so I has a clear referent. In body text, I can leave the author unidentified.