Technical Writing 101: A Crash Course
Suppose you have made the most incredible discovery the computer science industry has ever seen. Your years of studying, research, and hard work are finally going to pay off. However, do you know how to present this information to the world in a way that it can be understood? Welcome to the important role that technical writing plays in the computer science field. Even the greatest algorithm or the most helpful program can be a failure if it is documented in a way that is unclear, unhelpful, or incomplete.
As the people of the world become more technologically savvy, scientists in all disciplines are having to create documentation to support their work that will not only be viewed by a small community of those “in the know,” but by a much wider population with varying skill sets and education levels. In recognition of this trend, many universities are now including a general technical writing course as part of the core curriculum in undergraduate scientific disciplines. If you are given the opportunity to take one of these courses, then I strongly encourage you to do so. If not, then this list of tips will give you a basic foundation for documenting your work.
Know Your Audience
The most fundamental principle of technical communication is to write for your audience. Who will be reading the document you create? For example, you would compose a set of instructions very differently if you were writing for a group of programmers making modifications to your application, versus administrative support staff who utilize your application. Different audiences have different levels of knowledge, and what may be easily understandable to one user may be thoroughly confusing to another. If you are unsure of your audience, the general rule of thumb is to write on an eighth grade level. While this may sound like an excessive generalization, many companies, government agencies, and other institutions have adopted this policy to ensure that they are writing on a level that will reach the widest audience possible.
Consider Special Circumstances
While it may or may not apply to the subject you are writing about, it is always good to keep this in mind: Is there any potential for equipment damage, bodily injury, or other hazards by using whatever you have created? If so, then make sure it is documented in a clear and noticeable manner. Bold text, an increased font size, italics, or even a separate text box to make your disclaimers stand out are all good choices. No matter how slim the risk associated with your work may be, make sure it is documented. This is for your own safety and well-being, as well as that of your end users.
Plan Your Direction before You Begin
Using a flowchart or a similar diagramming method to organize your thought processes is a good place to start. If you have a rambling or repetitive document then your readers will become frustrated, confused, and may stop reading. Your document should have a clear beginning and a clear end, with appropriate transitions to guide the reader to the next section or step.
Avoid Jargon
Do not under any circumstances call a bug in your program an “undocumented feature.” In other words, avoid industry terms that will bog down your readers. Most readers in the general public will think of a computer as a computer rather than a terminal, processor, or any other colloquial language that tends to become interchangeable with the original word. While technical writers frequently decry jargon, a number of them fail to recognize jargon in real world applications and alienate their readers in the process.
Use Bullets or Numbered Lists
If you are outlining steps in a process that must be followed or referred to in a specific order, use a numbered list. This keeps the information in small, easy to process sections that can be quickly recalled and found again if necessary. If you have large quantities of information that require no specific order but still can be broken up, use a bulleted list. This prevents readers from being confronted with a wall of text that can be intimidating or confusing. Your chance of losing a reader’s interest and ability to follow your directions increases with longer blocks of disorganized information.
Visual Aids Are Your Friends
Remember the old saying that a picture is worth 1000 words? Take these words to heart. If you can use a diagram, chart, or picture to illustrate your point then by all means do so. This will assist readers who are visual learners, and by breaking up the text it will also allow your readers to have a new focus point, thus improving their retention.
Test Your Document
If you are familiar with your audience, look for an opportunity to have them read through your document. Ask them to comment on where they think more explanation could be helpful, and consider revisions to your document based on their feedback. If you have a series of steps you are asking your readers to follow, observe them doing so and notice any problem areas. If you have worked closely with the subject of your document for a long time, you may skip over information that has become innate to you without realizing it.
Remember, the steps listed herein are just a beginning point. Technical communication and the successful conveyance of information to your readers is an art that is learned through trial and error. Do not be discouraged if your first document requires multiple revisions before you are ready to release it to the public. If you would like to further explore the field of technical communication, the following references are a good place to turn to next.
References
- 1
- Alred, Gerald J., Brusaw, Charles T., and Oliu, Walter E. 2007. The Handbook of Technical Writing, Eighth Edition. St. Martin’s Press.
- 2
- Bremer, Michael. 1999. Untechnical Writing - How to Write About Technical Subjects and Products So Anyone Can Understand. Untechnical Press.
- 3
- Gerson, Sharon and Gerson, Steven. 2005. Technical Writing: Process and Product. Prentice Hall.
Biography
Leslie Sandoval (ldsandoval@salud.unm.edu) holds BA and MA degrees in English from New Mexico State University. She has worked as a technical writer for the Department of Defense and Department of Energy, and is currently pursuing her interests at the University of New Mexico.