CreateAStyleGuide.rst

<-- https://docs.google.com/document/d/1UUQEpZB9kcQ4zJFQp_Ez33aMvgoCx_nwh5ZBvvFu0ug/edit -->

Create a Style Guide

How to swim in the deep water - A lone writer’s guide to survival

Starting notes:

• Create a bare bones Style Guide
• Keep in mind that some "writers" are in fact some person who got stuck writing the docs but are really in Support, Product Engineering, or even Marketing.
• Try to provide real examples of what not to do. For example in a section on Writing for International Audiences, you might say - Don’t use words like “may”, use “might” or “can”. You might say - Avoid contractions - especially contractions that are in future or past tense or are passive, such as “wouldn’t”, “couldn’t”, “didn’t”. Depending on the “tone” you want to set for your docs, you might decide to use present tense contractions such as “don’t” or “can’t”.
• Here is a link to a resource with some ideas (it is too in-depth for a bare bones guide, but might trigger some thoughts: Style Guide Guide, a boilerplate for style guides)

Hack-a-thon content:

• 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