voice-001 should GuidesAPI docsMarketing Use a conversational, informal tone that is friendly without becoming overly colloquial, cutesy, or frivolous.
Voice and tone
Voice is the consistent style of the documentation. Tone varies with the reader’s situation. Use this page when you decide how formal, direct, or conversational the writing should sound.
For grammatical rules about person and tense and mood, see the grammar topics.
Keep the tone conversational
Section titled “Keep the tone conversational”Examples
- ✓ You’re ready to create your first project.
- ✗ The user may now proceed to project creation.
- ✗ Woo-hoo! Time to sprinkle some project magic!
Rationale
Conversational wording is familiar and easier to follow than stiff or formal wording. Excessive informality can distract from the task.
Use common contractions
Section titled “Use common contractions”voice-002 should Use familiar contractions, such as you’re, don’t, it’s, and can’t, to keep the tone informal and friendly.
Examples
- ✓ If you don’t set a timeout, the request waits indefinitely.
- ✗ If you do not set a timeout, the request waits indefinitely.
Rationale
Familiar contractions reduce formality without making a sentence harder to understand.
Don’t contract nouns with verbs
Section titled “Don’t contract nouns with verbs”voice-003 must GuidesAPI docsMarketingBlog Don’t form contractions by combining a noun with a verb. Write out the noun and verb in full.
Examples
- ✓ The build is finished when the status turns green.
- ✗ The build’s finished when the status turns green.
Rationale
A contraction such as the build’s finished can initially look like a possessive construction. Writing the noun and verb separately removes that ambiguity without affecting genuine possessives.
Avoid uncommon contractions
Section titled “Avoid uncommon contractions”voice-004 must GuidesAPI docsMarketingBlog Avoid awkward, uncommon, or multi-part contractions such as mightn’t’ve, could’ve, there’d, and it’ll.
Examples
- ✓ The server might not have received the request.
- ✗ The server mightn’t’ve received the request.
Rationale
The apostrophes in an uncommon or stacked contraction can obscure the words it combines.
Tell readers what to do
Section titled “Tell readers what to do”voice-005 should GuidesAPI docsMarketingBlog When task-oriented content offers more than one way to reach a goal, recommend one and say when to use the others. Don’t leave the reader to choose from an unranked list. A conceptual overview can list the approaches without recommending one, because describing them is its purpose. Use must for required actions, can for optional actions, might for possible outcomes, and We recommend for suggested actions. Don’t use should for actions; it leaves the reader unsure whether the action is required or recommended. Should is acceptable when quoting a requirement from a standard or specification that uses it.
Examples
- ✓ To create a bucket manually, use the console. To automate bucket creation, use the API.
- ✗ To create a bucket, use the CLI, the API, or the console.
Rationale
A recommended path spares a reader with a task from evaluating the options first. Fixed modal words tell readers how firm each statement is.
Don’t use please in instructions
Section titled “Don’t use please in instructions”voice-006 should GuidesAPI docsMarketingBlog Don’t use please in procedural instructions.
Examples
- ✓ Click Save.
- ✗ Please click Save.
Rationale
Please adds no information to an instruction. Removing it keeps the instruction concise and direct.
Define repurposed common words
Section titled “Define repurposed common words”voice-007 should GuidesAPI docsMarketingBlog Don’t use a common word in a new or industry-specific way without defining it in context.
Examples
- ✓ The client hydrates the page on first load. In this context, hydrates means that it attaches interactive behavior to the server-rendered HTML.
- ✗ The client hydrates the page on first load.
Rationale
Readers might apply the ordinary meaning and misunderstand the product behavior. A brief definition supplies the specialized meaning.
Lead instructions with a verb
Section titled “Lead instructions with a verb”voice-008 should GuidesAPI docsMarketingBlog Lead instructions with a verb. Remove openings such as You can, There is, There are, and There were when they delay the action.
Examples
- ✓ Configure the webhook in the dashboard.
- ✗ You can configure the webhook in the dashboard.
Rationale
Starting with the verb puts the action first, which helps readers find it when they scan instructions.
Don’t call things easy
Section titled “Don’t call things easy”voice-009 should GuidesAPI docsMarketingBlog Avoid phrases that trivialize difficulty, such as simply, easily, quickly, or It’s easy.
Examples
- ✓ To enable logging, add the
--verboseflag. - ✗ Simply add the
--verboseflag to enable logging.
Rationale
Difficulty depends on a reader’s experience and environment. Calling a task easy can frustrate someone who encounters a problem, and the label doesn’t help them complete the task.
Remove filler phrases
Section titled “Remove filler phrases”voice-010 should GuidesAPI docsMarketingBlog Remove filler phrases such as please note and at this time.
Examples
- ✓ The legacy endpoint doesn’t support pagination.
- ✗ Please note that the legacy endpoint doesn’t support pagination at this time.
Rationale
These phrases add length while the fact remains the same.
Applicable rules from other topics
Section titled “Applicable rules from other topics”- Address the reader as "you"
person-001should - Limit "we" to the organization
person-005should - Imperative mood for instructions
tense-005should - Use "is" and "has" directly
ai-007should - Avoid unsupported contrasts
ai-008should - Don't use redundant qualifiers
clarity-010should - Avoid unverifiable claims
claim-002should - Open with the subject, not the setting
skim-002should - Avoid humor
global-006should - Use exclamation points sparingly
punct-017should - Avoid internet slang
abbr-010should - Don't disparage any group
incl-024should
Deprecated rules
Section titled “Deprecated rules”voice-011(retired 2026-09-13): “Don’t use figures of speech or wording that disparages or insults any group of people.” Re-issued unchanged as incl-024 on the inclusive content page, because the rule is about who the wording targets, not how the documentation sounds. This page lists incl-024 under “Applicable rules from other topics”. The ID stays reserved and is never reused.