Style Guide

In the interest of making documentation more consistent, we aim to provide a set of style guidelines to make the documentation as useful as possible.

1. Each document should be formatted as numbered steps.
   Following the setup guide should be literally as easy as 1, 2, 3.
2. Assume the reader knows nothing.
   These guides should be written from the perspective of a complete novice to accomplishing the setup task. Conciseness is important, but should take a backseat to having a complete picture present.
3. Be concise.
   After writing for a complete novice, make sure the steps are concise. As a general rule of thumb, a step should contain no more than five actions and be accomplished in one physical location. For example, a step could combine "plug in" and "turn on", but should not combine "run cable" and "plug in", because running the cable requires physical movement.
4. A picture speaks a thousand words.
   A photo should be captured where plugging, unplugging, or identification of an object is concerned. Avoid long descriptions and capture an image where this is occurring. The object or action in question should be the primary focus of the photo, and annotations are encouraged where appropriate.
5. But not too many pictures.
   For the sake of clarity and flow of the document, no more than two photos should be included per step. If additional photos are needed, this is likely a good sign that a single step is too
6. Watch the jargon.
   Jargon, abbreviations, etc. should not be used before they have been defined. The jargon should be defined the first time it is used in each setup document where it is used. Precise definition is left to the author, but an example could be "SDI cable (thin black coaxial cable with a twist-lock connector on the end)". Describe the jargon in simple terms, even if this means going past the precise meaning of the acronym.
7. Avoid pronouns.
   Eliminate 'that' or 'it', unless it's abundantly clear what 'that' is referring to. It is always safer to mention the noun again. For example, use "Plug the SDI cable into the Camera Input socket." instead of "Plug it into the Camera Input socket."
8. Spell out numbers.
   Spell out numbers one through nine (1-9), use numerals for numbers 10 or above.There are two exceptions: The step number at the start of the step (in the list) should be a numeral regardless of value, and if a number begins a sentence, it should always be spelled out regardless of value.