A Crash Course in Technical Writing

By August 7, 2013 February 27th, 2016 General

While your job title may not be “technical writer”, it’s likely that at some point you will need to do some “technical writing” in your role. This could be as simple as whipping up some instructions, to writing a white paper or a full fledged technical brief. Regardless of the content and purpose, all such documents involve technical details which must be disseminated as effectively as possible. But doing so involves a slightly different strategy and approach than other types of written materials. In this article we’ll share a few short rules to keep in mind when it comes time for you to put on the technical writer’s hat.

The first tip is to realize that it’s all about style and consistently applying that style. If your company has a style guide then be sure to follow it, otherwise, consider using the following rules that we’ve found useful.

When writing instructions, always start with a verb in each step such as “Click”, “Open”, etc. This will make the steps read more consistent and help you get straight to the point. Avoid starting a step with a description first such as “To open a file, click Open under the File menu”. This sort of sentence structure is better used when there is only once step, as it describes both the subject and the instruction. However, multi-step instructions tend to read better with the instruction specified first.

Also, with instructions it’s best to use numbered lists and sub numbered lists as opposed to bullets, so the reader can track their progress better as they jump between the steps and the thing (e.g. software) that they’re trying the steps on.

One preferred style to live by when it comes to bulleted items, is to capitalize the first word of stand alone bullets, but to use smaller case when the bullet completes a sentence. For example, if you have a list of “key points” for the reader then capitalize the first word of each. However, if you introduced the points with a sentence like “The software is used for:”, then each bullet should complete this sentence and therefore start uncapitalized.

On a related note, some writers like to end each bullet with a semicolon, while others prefer commas. In the case where each point completes the sentence then the semicolon is a good way to go, with a period after the last bullet point. However, standalone items serve as individual paragraphs and are each best completed with periods.

When it comes to steps, we’ve found it useful to highlight things which the user must do in bold, while setting referenced items to italic. For example: “Click Open under the File menu”. This formatting makes it easy for the reader to see what to do, while also highlighting (with less emphasis) where they should do it.

Acronyms are another area where you can ease readability. The general rule we follow is that if an acronym is used three or more times, then introduce the acronym in parentheses after the first usage of the word(s) in the body of the content. If usage is less than three times, don’t bother using an acronym. If the first usage is in a title, then spell out the word(s) in full in that title, and wait for the first instance in the body to introduce the acronym.

Tables and figures are another common tool in many documents, and should be referenced as specifically as possible. Avoid using phrases like “see the following figure”, and instead use “See Figure 34 below”. Also be sure to use captions and cross references to those captions to ensure that the numbers will automatically update when new items are added. This rule can also be applied when referencing other sections, though we’ve found it useful to also include the section title in the reference to describe where the reader will be directed to.

When it comes to tables and figures, some of our clients prefer to have table captions above tables and figure captions below figures, the idea being that it makes for easier reading. Whichever style you choose, be sure to apply it consistently.

In terms of content don’t confuse general terms with names of things. We see a lot of content in which general things are mistaken for names and are therefore capitalized. For example, if your product has a feature called “Clone”, then capitalize it when referring to that feature. However, when using that term to reference a usage of that feature, we suggest using lower case (e.g. “…copy all clones…”).

Another content rule that makes for good style is to avoid using “-” in ranges and instead use “to”. This eliminates any confusion over negative numbers, and makes for more concise reading. We also recommend fully spelling out units instead of shortening them (e.g. use “seconds” instead of “secs.”). If you plan to use the abbreviations for units, then be sure to look up their proper capitalization before using them, and apply it consistently. For example, “MBps” and “Mbps” mean very different things.

One final content rule is around the proper use of “e.g.” and “i.e.”. The former is for examples, while the latter is for “as in” cases where additional clarity is to be added. We suggest wrapping these and the additional text in parenthesis, and to avoid adding a colon character after e.g. and i.e.

On a similar note, when it comes to numbers we always spell out the full word for zero through nine when used to describe a quantity (e.g. “…click the box two times…”). However for numeric quantities accompanied by a unit, we always use the number (e.g. 6 Mbps).

Our final tip is around formatting clarity. Documents are much more visually pleasing and easier to follow when their elements are grouped together. Therefore always be sure to use “keep with next” to ensure that things like figures and captions remain together when page breaks are encountered. If your styles are locked in Word, then this may not be an option, in which case consider inserting a page break instead. Just be sure to scan the rest of the document to see if any additional items need to be regrouped together.

We hope this article gives you a few ideas to keep in mind, next time the technical writer hat is thrown your way.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.