Increasing Clarity, Effectiveness, and Usability in Technical Documents


I will be posting a series of blog entries aimed at the improvement of clarity and effectiveness in existing as well as future documents. These sections are the product of an undergraduate technical writing class project at the University of Arizona. The project began with an attempt to discover a method of universalization in technical documents, however in this realm, said methods are endless on a global scale. Comments are greatly appreciated.

1: Document Overview
It is important to overview the layout of the entire document at the beginning. This acts to guide the reader through the document and also serves as a quick reference point as to where information exists throughout the document. This direction promotes ease of use and efficiency in completion of the process explained. It is important to outline to the user what they are going to be reading prior to the beginning of the actual instruction. With the implementation of this feature into the document, the user is easily able to skip to a certain sub step of the entire process or find quickly an area of confusion. It is also helpful to add navigation to sections for perhaps item/program specifications, frequently asked questions, and a contents or required materials list. Through this, writers are able to successfully make the process as a whole, appear much smaller and thus, easier to complete, while increasing efficiency simultaneously.
2: Text Style
It is important when creating a document to maintain a clear and straightforward organization of the document text. Develop a layout style that suits the document genre and stick to it. This includes maintaining consistency in any italicizing, bolding, or underlining of text for the purpose of designating or stating a difference in that text from the rest. A common method to employ is to italicize suggestions or hints from the writers which may be deemed helpful to the user. These comments are supplementary, and do not serve to detract from the documented instruction, but rather to bolster it. It is important to stay consistent to your style throughout the document, as it will be much easier for the reader to identify different parts of the instruction.
3: Depth of Instruction
An important factor to consider when in the beginning stages of document creation is to determine whether the document is intended to serve merely as a supplement/reference to an end user activity, or if the document is intended to serve as a detailed, step-by-step guide, which should be followed word for word. In the first situation, where the document is to serve as a reference, commonly called ‘Quick Reference’ or ‘Quick Start’ sheets, the most important document characteristics to have are organization and condensed information. Organization is vital to a quick reference sheet. In this case the user is either fully or mostly familiar with the task and is looking for a quick answer without having to read the entire instruction list. It is in these situations where diagrams and ‘Frequently Asked Questions’ are best used. Condensed information is also important to have here as the user is not looking for a detailed explanation per se, but rather a list of specifications, recommended settings, basic controls, etc. In the second situation, where a detailed procedure is described, there are a few different ideas to keep in mind. The key to creating a lengthy, detailed instruction document is to remain consistent in organization and procedure explanation. This means that regardless of the layout style that is ultimately chosen, you must remain consistent in that style. To veer away from what the document reader is already accustomed to, mid-document, is a sure fire way to confuse your reader.

4: Usability Testing
Usability testing is vital to successful document instruction. As a technical writer, it is easy to get involved in a project so much so, that we forget who will actually be reading the document. We must assume that they know nothing of the process or genre that we are writing about. If we are to create the most user friendly document that we possibly can, we have to write and format it in a way that even the user with the least applicable knowledge will be able to complete the task. Based on personal experience in a recent project, I have witnessed firsthand the importance of usability testing to the future success of a document. After several successful tests among writers, we had to change our documentation instruction considerably due to flaws which were revealed only in outside usability testing. We were fortunate enough to have a broad range of users in our usability tests. We had one tester who finished the process in one third of the average time (considerably faster), as well as testers who could not even complete the task.
5: Redundancy
Tiffany Kohnen writes on Technical Writing World about the need to convey a message clearly, but without redundancies. She notes that in her experience, “By not reducing redundancy in communication, you have completely destroyed all clarity.” I have also noticed this effect in the usability testing for our first project. We had several similar sections that were all vital to the completion of the task, and although our usability testers accepted and confirmed the importance of these sections, they stated that the redundancy of the instructions caused confusion. This type of confusion is not necessarily from any sort of contradictions in the text or flaws in the instructions, but rather too abrupt of an influx of information which caused the reader to feel overwhelmed with the process and therefore assume a natural feeling of misunderstanding. It is up to the technical writer to prevent this from happening to their own readers. Kohnen believes that the best way to avoid redundancies in the text is by “being concise.” That is, “shorten” and “condense” your writing to remove anything that is unnecessary, allowing the reader to focus on what is really important in your document. In doing this, we can increase clarity and understandability of technical documents.


Your email address will not be published. Required fields are marked *