person-001 should GuidesAPI docs Address the reader in second person (‘you’/‘your’) as the default throughout documentation.
Person and point of view
Documentation addresses the reader directly and keeps every other actor in third person. These rules pin down who “you”, “we”, and “the user” refer to so sentences never leave the actor ambiguous.
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 speaks directly to the reader and removes ambiguity about who performs an action, which suits instructions and reference alike.
Rewrite around singular “they”
Section titled “Rewrite around singular “they””person-002 should GuidesAPI docsMarketingBlog As an alternative to singular ‘they’, rewrite sentences using plural nouns or by omitting the pronoun altogether.
Examples
- ✓ Developers can restrict their tokens to a single project.
- ✗ Each developer can restrict their token to a single project.
Rationale
Recasting with a plural or no pronoun sidesteps the pronoun question entirely when “they” would read awkwardly.
Reserve “user” for end users
Section titled “Reserve “user” for end users”person-003 should GuidesAPI docsMarketingBlog Reserve the word ‘user’ for the end-user of the software being documented, not 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
If “user” means both the reader and the software’s end user, sentences get ambiguous about who acts.
Third person for software and end users
Section titled “Third person for software and end users”person-004 should GuidesAPI docsMarketingBlog Use third person when describing actions performed by software or end-users, reserving 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
Reserving second person for the reader keeps “you” meaning the reader, and third person for what the software or its users do.
Limit “we” to the organization
Section titled “Limit “we” to the organization”person-005 should GuidesAPI docsMarketingBlog Limit first-person plural (‘we’/‘our’/‘us’) to references to the authoring organization with an unambiguous antecedent; 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
“We” is ambiguous about who it means, so limiting it to the authoring organization keeps the actor clear.
Restrict “I” to UI text and FAQs
Section titled “Restrict “I” to UI text and FAQs”person-006 should GuidesAPI docsMarketingBlog Restrict first-person singular (‘I’/‘me’) to UI text written from the user’s point of view, such as checkbox labels, and to 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
First person fits UI text spoken as the user and FAQ questions, but in body text it is unclear who “I” is.