sentence-001 should GuidesAPI docsMarketingBlog Give every pronoun a clear antecedent. Follow a demonstrative such as this or these with a noun.
Sentence structure
Sentence structure shows how the words and clauses in a sentence relate. Use this page for pronoun references, restrictive and nonrestrictive clauses, final prepositions, and articles.
Sentence length and word order are on the clarity and precision page. The choice of voice is on the active and passive voice page.
Give every pronoun a clear antecedent
Section titled “Give every pronoun a clear antecedent”Examples
- ✓ The CLI caches credentials and refreshes tokens. This behavior reduces login prompts.
- ✗ The CLI caches credentials and refreshes tokens. This reduces login prompts.
Rationale
An unclear pronoun makes the reader stop and determine which noun or idea 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). Don’t 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
Choosing that or which changes what the sentence means. A restrictive clause identifies which members of a group the sentence covers. A nonrestrictive clause adds information about members already identified.
Prepositions at the end of sentences
Section titled “Prepositions at the end of sentences”sentence-003 should GuidesAPI docsMarketingBlog End a sentence with a preposition if it sounds more natural and is easier to comprehend. Don’t rewrite a sentence into an awkward form to avoid a final preposition.
Examples
- ✓ Choose the region you want to deploy to.
- ✗ Choose the region to which you want to deploy.
Rationale
A sentence rewritten to avoid a final preposition usually adds words and a formal construction that is harder to comprehend.
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. Don’t omit them for brevity.
Examples
- ✓ The response includes a token and an expiry timestamp.
- ✗ Response includes token and expiry timestamp.
Rationale
Articles tell the reader whether a noun is specific or is one member of a group. Without them, token could mean a specific token or any token.