Technical Writers

Quick tips

Company terminology

• Don’t shorten Aperture Science’s product names.

• Don’t use internal product codenames in public-facing documentation.

---

Grammar

• Use the active voice whenever possible.

• Use second-person pronouns like you and your to address the reader.

• Use the singular they as a gender-neutral pronoun.

• Use standard American English spelling conventions.

• Use the present tense whenever possible.

---

Punctuation

• Use serial commas.

---

Tone and content

• Strive for an approachable, friendly tone.

• Write for a broad audience, not just for experts.

• Avoid filler words.

• Try to use short, simple words instead of complex, abstract words.

---

Formatting and organization

• Introduce code samples with a summary or description of what the code does.

• Put captions after their associated image.

• Use screenshots sparingly.

• Use descriptive link text.

• Introduce procedural instructions with a summary or description of what the procedure is for.

• Use title case for titles.

• Use sentence case for headings.

• After each heading, include a summary or description of the following section.

---

User interfaces

• If the reader must interact with a specific UI element, put the name of that UI element in bold.

• Try to write task-oriented instructions.

• Use angle brackets to describe the process of navigating multiple menu items in a row.

• Use select instead of click.

---

APIs and SDKs

• Describe (almost) everything.