clarity-001 should GuidesAPI docs Avoid jargon; when jargon is necessary for the audience or SEO, define it on first use or link to a trusted definition.
Clarity and precision
Clear writing is mostly subtraction: fewer clauses, shorter words, no filler. These rules keep sentences parseable for readers and for translators. Term-level consistency is covered in word choice, and register is covered in voice and tone.
Define necessary jargon
Section titled “Define necessary jargon”Examples
- ✓ The API uses idempotency keys — unique values that make retries safe — to deduplicate requests.
- ✗ The API uses idempotency keys to deduplicate requests.
Rationale
Undefined jargon stops a reader who does not share the author’s background; defining or linking it keeps the content open to its whole audience.
Prefer plain words
Section titled “Prefer plain words”clarity-002 should GuidesAPI docs Use simple, plain-language words; prefer shorter, more familiar alternatives over complex or obscure ones.
Examples
- ✓ Use this endpoint to authenticate.
- ✗ Utilize this endpoint to facilitate authentication.
Rationale
A shorter, familiar word is faster to read and easier to translate than an obscure one that carries no extra meaning.
Write concisely
Section titled “Write concisely”clarity-003 should GuidesAPI docs Write concisely; prune unnecessary words, adverbs, and filler phrases.
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.
Rationale
Filler words make a reader work harder to find the point, so pruning them speeds comprehension.
Avoid non-English words and abbreviations
Section titled “Avoid non-English words and abbreviations”clarity-004 should GuidesAPI docsMarketingBlog Avoid non-English words and phrases (de facto, ad hoc) and Latin abbreviations such as ‘e.g.’ and ‘i.e.’; use plain English equivalents instead.
Examples
- ✓ Batch endpoints (for example,
/v1/batch) accept up to 100 operations. - ✗ Batch endpoints (e.g.,
/v1/batch) accept up to 100 operations.
Rationale
Latin abbreviations and non-English phrases trip up non-native readers and translators, while the plain English equivalent is unambiguous.
Keep sentences short
Section titled “Keep sentences short”clarity-005 should GuidesAPI docsMarketingBlog Write short, simple sentences. Avoid complex sentence structures with multiple clauses.
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, multi-clause sentence is harder to parse and to translate; short sentences keep each idea separate.
Use subject-verb-object order
Section titled “Use subject-verb-object order”clarity-006 should GuidesAPI docsMarketingBlog Use standard subject-verb-object word order.
Examples
- ✓ The endpoint returns a paginated list of results.
- ✗ Returned by the endpoint is a paginated list of results.
Rationale
Standard subject-verb-object order is what readers and machine translators expect, so it is the easiest to parse.
Limit stacked noun modifiers
Section titled “Limit stacked noun modifiers”clarity-007 should GuidesAPI docsMarketingBlog Avoid modifier stacks; do not use more than two nouns as modifiers of another noun.
Examples
- ✓ Update the setting that controls the upgrade policy for node pools.
- ✗ Update the cluster node pool upgrade policy setting.
Rationale
A pile of nouns modifying a noun is ambiguous about what modifies what, so limiting the stack keeps the meaning clear.
Keep structural helper words
Section titled “Keep structural helper words”clarity-008 should GuidesAPI docsMarketingBlog Include helper words such as ‘that’, ‘who’, and ‘the’ to clarify sentence structure.
Examples
- ✓ Make sure that the value you pass matches the schema that the endpoint expects.
- ✗ Make sure the value you pass matches the schema the endpoint expects.
Rationale
Optional words like “that” and “the” mark sentence structure that readers and translators otherwise have to infer.
Prefer single verbs to phrasal verbs
Section titled “Prefer single verbs to phrasal verbs”clarity-009 should GuidesAPI docsMarketingBlog Avoid phrasal verbs when a simpler single verb is available.
Examples
- ✓ Configure the connection before you run the migration.
- ✗ Set up the connection before you carry out the migration.
Rationale
A phrasal verb such as “set up” has meanings that do not follow from its parts, so a single verb like “configure” is clearer for non-native readers and translation.