lone-writers-guide

Create a Style Guide

Getting Started

when you’re ready to start a company style guide, here are some general ideas about how to do it.

• Choose an external style guide (Microsoft Manual of Style, Chicago, etc.)
• Company product names, including correct trademark attribution, capitalization, and any allowed short forms.
• English, British, Australian, English?

• Style

  • Present tense
  • Second person
  • Active voice
  • Conversational tone
  • Do not use courtesies (please, thank you, and so on)
  • Decide whether to use contractions

• Title vs. sentence case for:

  • Headings
  • Figure captions
  • Table titles
  • Table column headings

• Consider global and ESL readers

  • One word, one meaning
  • Do not use colloquialisms
  • Do not use idioms

• Parallelism in:

  • Presenting all tasks the same way (e.g., start with a prerequisite, then numbered steps, then a postreq/what to do next)
  • Bullet lists - Within a given list, all bullets should be phrases or sentences. (Note that this Style Guide doesn’t follow this recommendation. At times, such as for internal use only, it’s not worth the time to reach for perfection.)
  • Same order of info/syntax/examples for all reference sections

• Basic graphics/screenshot guidelines:

  • Source tool (e.g., Snagit, Visio, Omnigraffle, etc.)
  • Output format (SVG, PNG, etc.)
  • Callout style (wording and line color/width/style)

• Legalese page - get the Legal department to sign off:

  • Third party references
  • Disclaimers (use product at your own risk)
  • Proprietary/confidentiality statements
  • Copyright

• Progressive disclosure

  • One idea per paragraph
  • Paragraphs follow each other in a logical order

  Copyedit checklist:

  • spell check

  • punctuation:

  ** check for double spaces

  ** if you used the following correctly:

  *** .. extra period - check for and delete

  *** , comma

  *** ; semi-colon

  *** : colon

  *** () parenthesis

  *** ‘ apostrophe

  • subject/verb agreement

  • numerals

  • fonts and capitalization

  • headings - logical and in order

  • tables - are table formats consistent?

  • links - correct and working

  • headers and footers, if you’re using

  • notes & peripheral data - footnotes, endnotes, appendixe