Paul Clifton is a Ph.D. student in Digital Media at the Georgia Institute of Technology. He has been an on and off technical writer with Shoap Technical Services since 2007 and is currently working in interaction and user experience design at Intel.
Recently, I helped my friend update his resume. I’d helped him make a brand new one a few years before, and it had been an extremely painful process, so when he asked me to help update it, I nearly just said no. To my surprise, the draft he sent me proved that he had been paying attention when I had originally explained the rules for making a good resume, why they were the rules, and why following them mattered. His grammar and spelling still weren’t very good, but grammar and spelling are the easy part. Clearly communicating complex information by meeting the expectations of the reader is the hard part, and I was happy to see that he had pretty well taken care of that.
Whether we think about it or not, we all follow rules when we communicate. Besides the obvious rules like spelling and punctuation, there are rules that dictate things like word order, and there are idiomatic rules that determine the meaning of certain phrases. These rules have evolved over thousands of years to facilitate understanding between people, and now that we are communicating about subjects that are somewhat more complex than where the food is, we have more nuanced rules to follow. In the case of technical documentation, these rules come from two main sources: the reader and similar documents that already exist. These rules are rarely codified but not following them can confuse a reader and severely decrease the value of a document, while being aware of them and following them can ensure that a reader can get the information that he needs without being frustrated and ultimately ignoring the document completely.
As technical writers, it is our job to distill the rules we need to follow to make our documents valuable. We do this by understanding our readers and being familiar with lots of technical documents. Understanding our readers involves talking to them, getting a sense of the culture at their company (department names and responsibilities) and finding out what expectations they bring to internal and external documents (jargon, organization, purpose). Being familiar with other documents involves actually reading them. I am not ashamed to admit that I will read an entire manual before plugging in and turning on a new TV. By understanding our readers and by being aware of different types of documents, we can make decisions about how best to serve the needs of our clients. For example, an API guide and a quick-start developers guide provide a lot of the same kinds of information: function names, parameters, return types, etc., but API guides are meant to be references; they should be easily searchable and the information should be immediately clear, while quick-start developer guides are intended to bring a developer up to speed on how to work with a new API, and therefore normally walk a developer through a typical step-by-step process for accomplishing some standard task. Within these two types of documents there are many nuanced rules that we follow to meet readers’ expectations so that when they look at the document they can easily understand the information instead of walking away, frustrated by not being able to figure out what we were trying to say.
As technical writers, we have paid close attention to the subtleties of different types of documents and, therefore, have a good general understanding of what a particular project requires; however, for every project, we have to develop a new set of rules that incorporates not only spelling, grammar, and formatting, but also the reader and the context in which the document will be read. It may be hard to call them rules if they change for every document, but consistency is key and the only way to be consistent is to establish a set of parameters to adhere to, and understanding and developing those parameters is definitely the hardest yet most satisfying part of our job.