Style guide top-ten list #

This page provides a top-ten list of the most important grammatical and stylistic considerations when writing Starburst technical content. For more information on each of these rules, see the Google developer documentation style guide.

1. Active voice
   • The subject of the sentence should be the person or thing that is performing the verb’s action, rather than the person or thing that is being affected by the verb’s action.
     • DO: Starburst Academy offers hands-on, self-paced training courses.
     • DON’T: Hands-on, self-paced training courses are offered by Starburst Academy.
2. Present tense
   • Actions and events should happen in the present moment; they should not occur in the past or future.
3. Second person
   • Refer to the reader as “you” rather than “the user” or “the customer.”
4. Sentence case
   • In headings and titles, capitalize only the first word.
5. Conditionals first
   • Mention the circumstances or context of an action before the action itself. For example, refer to the location of a button before telling the reader to click the button.
6. Bold UI elements
   • Put the name of all UI elements you refer to in bold.
7. Bulleted list formatting
   • Start each bulleted list item with a capital letter.
   • For list items containing run-in headings, end the run-in heading with a colon. Bold both the text and the colon. Start the text that follows the colon with a lowercase letter.
   • If the description contains a verb or is a standalone thought, end the list item with a period (or other suitable sentence-ending punctuation mark). If the description contains a comma-separated list or a phrase without a verb, end the list item without punctuation.
     • Punctuation: this description contains a verb.
     • No punctuation: comma-separated lists, short phrases, descriptions without verbs
8. Avoid jargon, colloquialisms and humor
   • Whenever possible, choose plain, unambiguous language that is accessible to global readers.
9. Pronouns
   • Always ensure that references between a pronoun and its antecedent are clear. When in doubt, use the antecedent and not the pronoun.
10. Use of apostrophes
    • To form a possessive of a noun, append ’s to the end of the noun. However, if the noun is plural and ends with the letter s, append only ’ to the end of the noun, without an additional s.
    • To form a possessive of the pronoun it, append only the letter s, without ’. Appending ’s to the end of it forms a contraction for it is.
      • Possessive: Its
      • Contraction: It’s