6 tips for successful documentation

Posted on: February 19, 2014 | By: Ryan Gay | Filed under: Tech Tips

When it comes to creating documentation used to instruct others, many automatically freeze up about how to approach the process. What will their co-workers think? What if there is an error I missed? How do I even go about writing effective instructions for a new process or procedure? These are all legitimate questions faced by anyone tasked with writing documentation. Here are some of the top tips for writing successful documentation.

1. Don’t make assumptions

When it comes to writing documentation, you need to be aware of your audience. Consider their technical level of expertise in the area, but never assume that a person reading your documentation will understand something you feel is second nature. This is particularly true when using acronyms. You should always identify the acronym technically first, followed by the acronym in parenthesis; e.g., Instructional and Campus Technologies (I&CT).

2. Be clear and concise

When writing documentation, keep your steps clear and concise. It’s important not to assume that readers will remember everything on the first try. You should stay away from paragraphs and keep sentences simple and to the point. It’s helpful to eliminate redundancies—if you can remove a word and not lose meaning to the sentence, you should cut it.

3. Maintain style

In order to develop clear and recognizable documentation, you should develop your style and stick to it. If you are working with a team, organize a meeting to discuss things like structure, layout, grammar, and punctuation. Language is a tricky tool that has garnered a variety of schools of learning, all with their own distinct opinions. For instance, the argument over whether or not to use the Oxford comma.

4. Organization is key

Your readers won’t be able to follow your instructions if they are disorganized. The best way to avoid these issues is to outline your documentation ahead of time. This will help you avoid jumping from topic to topic unnecessarily and will allow your readers to follow you easily. Further, you might find it easier to write if you already have the roadmap in your mind.

5. Anticipate problems

When it comes to following documentation, if a user can take a wrong step, they probably will. To make your documentation even more effective, you should look at the problem from different angles. What sorts of problems might others come across? What about users who have no prior knowledge of the subject or process? Anticipating these issues help eliminate confusion and prevent users from abandoning the documentation.

6. Test your documentation

This is one of the most important things anyone writing documentation should accomplish. You have to know that your documentation will work, otherwise, why send it out to others? Even if you have a strong plan mapping out contingencies, there’s nothing quite like going through the process like you had never seen it before. It’s also a nice way to cover your bases! Some also find it helpful to have a colleague test the documentation. This way, you can quickly learn what might cause problems from a user’s point of view.

If you can follow and accomplish these general steps when writing your documentation, others will have no problems following your instructions to reach the intended goal. For those interested in learning about the mechanical aspects of documentation writing, we will explore those in the next part of this blog series.

Image by Flickr user Betsy Weber

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.