voice-001 should GuidesAPI docs Write in a conversational, informal tone: friendly and approachable, but not overly colloquial, cutesy, or frivolous.
Voice and tone
This page defines how documentation sounds: a conversational, friendly register that stays direct and respects the reader’s time and situation. It covers tone, contractions, and phrasing habits; the grammatical mechanics of person, tense, and mood live in the grammar section.
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
A friendly, plain register is easier to read than a stiff or overly formal one, without tipping into cutesy.
Use common contractions
Section titled “Use common contractions”voice-002 should GuidesAPI docs Use common contractions (you’re, don’t, it’s, can’t) to maintain an informal, friendly tone.
Examples
- ✓ If you don’t set a timeout, the request waits indefinitely.
- ✗ If you do not set a timeout, the request waits indefinitely.
Rationale
Contractions match how people actually speak, which keeps the tone approachable and the sentences natural.
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 noun followed by apostrophe-s reads first as a possessive, so a reader parses “the team’s finished” as a possessive and has to re-read when it doesn’t resolve. Writing the verb out avoids the double-take; genuine possessives are unaffected.
Avoid uncommon contractions
Section titled “Avoid uncommon contractions”voice-004 must GuidesAPI docsMarketingBlog Avoid awkward, uncommon, or multi-part contractions (mightn’t’ve, could’ve, there’d, it’ll) that may confuse non-native English speakers.
Examples
- ✓ There would be no record of the request, and it will fail silently.
- ✗ There’d be no record of the request, and it’ll fail silently.
Rationale
Uncommon or stacked contractions are hard to parse, especially for non-native readers.
Tell readers what to do
Section titled “Tell readers what to do”voice-005 should GuidesAPI docsMarketingBlog Write prescriptively: tell readers what to do rather than presenting a list of options. Use ‘must’ for required actions, ‘can’ for optional actions, ‘might’ for possible outcomes, and ‘We recommend’ for suggested actions; generally avoid ‘should.’
Examples
- ✓ To create a bucket, use the CLI.
- ✗ There are several ways to create a bucket: the CLI, the API, or the console.
Rationale
Telling the reader what to do, with consistent modal words, removes the guesswork of choosing among options.
Don’t say please in instructions
Section titled “Don’t say please in instructions”voice-006 should GuidesAPI docsMarketingBlog Do not use ‘please’ in procedural instructions.
Examples
- ✓ Click Save.
- ✗ Please click Save.
Rationale
“Please” adds nothing to an instruction and can read as pleading rather than direct.
Define repurposed common words
Section titled “Define repurposed common words”voice-007 should GuidesAPI docsMarketingBlog Do not use common words in new or industry-specific ways without defining them in context.
Examples
- ✓ The client hydrates the page — that is, attaches interactive behavior to the server-rendered HTML — on first load.
- ✗ The client hydrates the page on first load.
Rationale
Using a common word in a special sense without saying so misleads a reader who knows only the ordinary meaning.
Lead with a verb
Section titled “Lead with a verb”voice-008 should GuidesAPI docsMarketingBlog Lead sentences and instructions with a verb; edit out weak openers like ‘You can’ and ‘There is/are/were.’
Examples
- ✓ Configure the webhook in the dashboard.
- ✗ You can configure the webhook in the dashboard.
Rationale
Leading with the verb puts the action first, so a reader scanning steps sees what to do immediately.
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
Calling a task simple or easy makes a stuck reader feel worse and adds nothing to the instruction.
Cut placeholder phrases
Section titled “Cut placeholder phrases”voice-010 should GuidesAPI docsMarketingBlog Avoid placeholder 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
Phrases like “please note” and “at this time” delay the point without adding meaning.
Don’t denigrate any group
Section titled “Don’t denigrate any group”voice-011 should GuidesAPI docsMarketingBlog Avoid ableist language, figures of speech, and phrasing that denigrates or insults any group of people.
Examples
- ✓ The configuration requires no coding experience.
- ✗ The configuration is so simple your grandmother could do it.
Rationale
Language that demeans a group alienates readers and rarely serves the point.