How to present clear documentation

Posted on: March 5, 2014 | By: Ryan Gay | Filed under: Tech Tips

Previously, we took a look at how to create successful documentation used to instruct others. Now that you know more about the broader ideas of being able to effectively communicate instructions, it’s time to take a closer look at the actual presentation of the information.

When it comes to documentation, it helps to take into account the VARK theory of learning preferences. VARK covers the four basic types of ways people learn – Visual, Auditory, Read/Write, and Kinesthetic. When it comes to creating written documentation, auditory learners are the most difficult to address. However, depending on your capabilities, you may consider utilizing different mediums, such as podcasts, narration, or webinars. Since the visual, read/write, and kinesthetic learners are easier to target in written or online documentation, let’s take a look at some helpful tips to consider the next time you create a set of instructions.

1. Start with your scope and purpose

Begin your documentation with the scope and purpose of your instructions. Depending on the topic, you might be describing how to accomplish a broad set of objectives, or something more specific. The scope helps define your audience and the purpose provides clear expectations to the user of what they will learn. These instructions are for users looking to solve the Outlook.com exception error or The purpose of this documentation is to instruct users on successfully mapping your network drives are good examples.

2. Use numbered steps

Numbered steps are a great way to maintain structure in your document. Steps provide clear markers to users of where they are in the process they are trying to accomplish, and helps reduce the likelihood of error.

3. Use pictures

They say a picture is worth a thousand words, and many readers respond well to visual cues. When matched with a numbered step, a picture can help the user remain on the path to success. Additionally, they allow you to communicate more information with less text and give the user confidence they are following the process correctly. For Windows users, try using the Snipping Tool. If you’re on a Mac, press CMD+SHIFT+3 for a full screen capture, or CMD+SHIFT+4 to select the area you want show.

4. Provide examples

Concrete examples illustrate concepts by providing the user with something they can relate to. While examples provide further clarification to a more complicated topic, they also give you the freedom to point out those tricky exceptions. Keep in mind, you should always highlight any possible deviations from procedure.

5. Use tips, warnings, or notes

Tips, warnings, and notes are a great way to draw attention to important messages in your documentation. It’s easy for someone to stop paying attention by step 15; but, if you have a nice, bright warning that the following steps are easy to miss, you’re bound to grab the reader’s attention once again.

6. Use headings

Headings are a great way to break up your instructions. Many people are read/write learners, meaning that they learn best when reading. But, even the most dedicated readers will let their eyes glaze over every now and then. Headings are a great way to draw attention and break up those potentially long, clunky paragraphs.

If you can follow and accomplish these mechanical aspects of writing your documentation, others will have no problems following your instructions to reach the intended goal.

Image by Flickr user Richard

Ryan Gay

Ryan is the Manager of Service Management & IT Project Lead for Instructional & Campus Technologies. He has received both undergraduate and graduate degrees in English from UNC-Greensboro.

More Posts - Website

 

Comments are closed.