sentence-001 should GuidesAPI docsMarketingBlog Ensure every pronoun has a clear, unambiguous antecedent; follow demonstrative pronouns (this, these) with an explicit noun.
Sentence structure
These rules keep individual sentences unambiguous: every pronoun points somewhere, relative clauses signal whether they restrict, and small words stay in. Voice is covered separately under active and passive voice.
Give every pronoun a clear antecedent
Section titled “Give every pronoun a clear antecedent”Examples
- ✓ The CLI caches credentials and refreshes tokens. This caching reduces login prompts.
- ✗ The CLI caches credentials and refreshes tokens. This reduces login prompts.
Rationale
A pronoun with no clear antecedent leaves the reader guessing what it refers to.
That and which
Section titled “That and which”sentence-002 should GuidesAPI docsMarketingBlog Use ‘that’ for restrictive clauses (no preceding comma) and ‘which’ for nonrestrictive clauses (preceded by a comma); do not substitute one for the other.
Examples
- ✓ Delete the log files that are older than 30 days.
- ✗ Delete the log files which are older than 30 days.
- ✓ The
--forceflag, which skips confirmation, is optional. - ✗ The
--forceflag, that skips confirmation, is optional.
Rationale
The comma and the word signal whether the clause is essential or extra, so using them correctly preserves the meaning.
Prepositions at the end are fine
Section titled “Prepositions at the end are fine”sentence-003 should GuidesAPI docsMarketingBlog End a sentence with a preposition when doing so produces a more natural or readable sentence; do not rewrite awkwardly to avoid a terminal preposition.
Examples
- ✓ Choose the region you want to deploy to.
- ✗ Choose the region to which you want to deploy.
Rationale
Contorting a sentence to avoid ending in a preposition usually reads worse than just ending in one.
Don’t drop articles
Section titled “Don’t drop articles”sentence-004 should GuidesAPI docsMarketingBlog Always include definite and indefinite articles (a, an, the) in body text and headings; do not omit them for brevity.
Examples
- ✓ The response includes a token and an expiry timestamp.
- ✗ Response includes token and expiry timestamp.
Rationale
Dropping articles for brevity reads as terse and can be ambiguous.