Clarity and precision

Clear and precise documentation states one meaning in language readers can understand. Use this page when you choose words, shape sentences, or revise text that is difficult to understand or translate.

For guidance on consistent terminology, see the word choice topic. For voice and formality, see the voice and tone topic.

Avoid unnecessary jargon and define necessary jargon

clarity-001 should GuidesAPI docsMarketing

Use an established, widely understood term when it accurately names a concept. Don’t replace it with terminology used only within your organization, among close partners, or in marketing. Use a specialized term only when it names a meaningful distinction or is the established term for the concept, and define it on first use.

Examples

✓ The model uses speculative decoding, a technique in which a smaller model generates candidate tokens for the main model to verify.
✗ The model uses speculative decoding to reduce latency.
✓ The robot uploads its logs to the server.
✗ The robot uploads its logs to the fleet host. (When “fleet host” is the robotics team’s name for an ordinary server.)

Rationale

Jargon is terminology whose meaning depends on knowledge shared by a particular organization, partner group, marketing program, or technical specialty. A term doesn’t become widely understood merely because a product team and its closest partners use it routinely.

Creating a new name for an established concept forces readers to learn an unnecessary synonym and makes relevant information harder to find. A specialized term is useful when it expresses a distinction that established vocabulary doesn’t capture or when it has become the accepted industry term. Define such a term when readers new to the field might not know it.

New terminology can become established over time. Look for independent, widespread use outside your organization rather than relying on internal documents, product marketing, or familiarity among existing partners.

Prefer plain words

clarity-002 should GuidesAPI docsMarketing

Prefer simple, familiar words to complex or obscure alternatives.

Examples

✓ Use this endpoint to authenticate.
✗ Utilize this endpoint to facilitate authentication.

Rationale

A familiar word conveys the meaning without making readers interpret unnecessary vocabulary. It is also easier to translate consistently.

Write concisely

clarity-003 should GuidesAPI docsMarketing

Remove words, adverbs, and filler phrases that don’t add meaning.

Examples

✓ To delete a project, first remove its resources.
✗ In order to delete a project, it is first necessary to remove all of its resources.
✗ To delete a project, first remove its resources, ensuring a smooth and successful deletion.

Rationale

Extra words delay the instruction or fact that the reader needs.

Avoid non-English words and abbreviations

clarity-004 should GuidesAPI docsMarketingBlog

Use plain English instead of non-English words and phrases such as de facto and ad hoc, or Latin abbreviations such as e.g. and i.e. in body text.

Examples

✓ Batch endpoints (for example, /v1/batch) accept up to 100 operations.
✗ Batch endpoints (e.g., /v1/batch) accept up to 100 operations.

Rationale

Readers might not recognize a borrowed phrase or understand how a Latin abbreviation is used. Plain English states the meaning directly and gives translators a complete phrase to work with.

Keep sentences short

clarity-005 should GuidesAPI docsMarketingBlog

Keep sentences short and focused on one idea. Split a sentence with several clauses when each clause can stand on its own.

Examples

✓ Tokens expire after 24 hours unless you request a longer lifetime. After a token expires, the client must reauthenticate.
✗ When the token expires, which happens after 24 hours unless you request a longer lifetime, the client must reauthenticate before it can send more requests.

Rationale

A long sentence with several clauses can hide the relationship between ideas. Shorter sentences make each idea easier to follow and translate.

Use subject-verb-object order

clarity-006 should GuidesAPI docsMarketingBlog

Place the subject before the verb and the object after it.

Examples

✓ The endpoint returns a paginated list of results.
✗ Returned by the endpoint is a paginated list of results.

Rationale

Subject-verb-object order makes the sentence’s grammatical relationships explicit. An inverted sentence makes those relationships harder for readers and translators to identify.

Limit stacked noun modifiers

clarity-007 should GuidesAPI docsMarketingBlog

Don’t use more than two nouns to modify another noun.

Examples

✓ Update the setting that controls the upgrade policy for node pools.
✗ Update the cluster node pool upgrade policy setting.

Rationale

In a long noun stack, readers must decide which nouns modify which others. Expanding the stack into a phrase makes those relationships explicit.

Replace unclear phrasal verbs

clarity-009 should GuidesAPI docsMarketingBlog

Replace a phrasal verb when another verb expresses the same meaning more clearly. Keep established phrases such as set up and sign in when they are the clearest terms for the action.

Examples

✓ Run the migration.
✗ Carry out the migration.
✓ Set up the connection before you run the migration.

Rationale

Some phrasal verbs are idiomatic and can be difficult to interpret or translate. However, a single verb isn’t inherently clearer: it might be more formal, less familiar, or have a different meaning. Choose the verb or verb phrase based on meaning and established usage, not word count.

Don’t use redundant qualifiers

clarity-010 should GuidesAPI docsMarketingBlog

Qualify a statement once. Don’t combine several modal verbs and qualifying words in one statement, as in could potentially, may possibly help to, or might be able to. Choose a word that expresses the degree of certainty, or state the fact without a qualifier.

Examples

✓ Enabling compression can reduce the payload size.
✗ Enabling compression could potentially possibly help to reduce the payload size.

Rationale

Each added qualifier makes the degree of uncertainty harder to interpret. One precise modal verb communicates that uncertainty.

Clarify ambiguous noun phrases

clarity-011 should GuidesAPI docsMarketingBlog

When a noun phrase doesn’t clearly identify the intended concept or item, replace it with a complete, specific phrase. Use abstract wording rather than the abstract, reference documentation rather than the reference, and the specific header name rather than the header when several headers have been mentioned. A shorter reference is fine when the context identifies only one possible item.

Examples

✓ Avoid abstract wording that adds style without meaning.
✗ Avoid the abstract.
✓ The response includes the Retry-After and X-RateLimit-Reset headers. Retry the request after the delay in the Retry-After header.
✗ The response includes the Retry-After and X-RateLimit-Reset headers. Retry the request after the delay in the header.
✓ The response includes a Retry-After header. Retry the request after the delay in the header.

Rationale

An unclear reference makes readers infer which concept or item the writer means. Naming it removes the ambiguity, while repeating a name that context already makes clear adds unnecessary text. Pronouns without clear antecedents are covered by sentence-001.

Applicable rules from other topics

Deprecated rules

clarity-008 (retired 2026-09-13): “Include helper words such as that, who, and the to clarify sentence structure.” Retired because the omission it targeted rarely causes a misreading: dropping that after a verb such as verify slows a reader only briefly, and only when the subject is long, which clarity-005 already addresses. Articles are covered by sentence-004 and relative pronouns by sentence-002, so the rule was either a restatement or a judgment call. Google and Microsoft state the rule for translation, but that benefit is not demonstrated for current translation systems. The ID stays reserved and is never reused.