word-001 should GuidesAPI docsMarketingBlog Use one term consistently to represent one concept across all documentation.
Word choice
Consistent word choice prevents synonyms from implying distinctions that don’t exist. This page also covers and rather than as well as, and verbs used as nouns. Use this page for recurring patterns in sentences and the word list for guidance on a specific term.
One term per concept
Section titled “One term per concept”Examples
- ✓ Select a region. After you select a region, the zone list updates.
- ✗ Select a region. After you choose a region, the zone list updates.
Rationale
Switching terms for the same concept can imply that the terms name different things. A consistent term also gives translators a stable equivalent. AI-generated text often substitutes synonyms for a repeated word, so check generated drafts for unnecessary variation.
Use “and”, not “as well as”
Section titled “Use “and”, not “as well as””word-002 should GuidesAPI docsMarketingBlog Join items with and rather than as well as. As well as adds length without adding meaning, and it can obscure whether the items carry equal weight.
Examples
- ✓ The SDK supports Python and Go.
- ✗ The SDK supports Python as well as Go.
Rationale
As well as can imply that the second item is secondary. And doesn’t rank them.
Don’t use verbs as colloquial nouns
Section titled “Don’t use verbs as colloquial nouns”word-003 should GuidesAPI docsMarketingBlog Don’t use a verb as a colloquial noun, such as the ask for a request, the tell for a sign, the lift for the effort, or the spend for the cost. Use the plain noun. Established technical nouns that grew from verbs (a build, a commit, a release) are fine.
Examples
- ✓ The request is small: one configuration change.
- ✗ The ask is small: one configuration change.
Rationale
Terms such as the ask come from business slang and can be unfamiliar or difficult to translate. The established noun states the same idea without importing a corporate tone.