The Technical Writer’s Guide to Technical Writing
What do an instruction manual, a press release, and a business proposal have in common? Well, despite their difference in purpose, language, and distribution, they all fall under the umbrella of a process called technical writing. Technical writing is any piece of literature that is produced in an informational, professional, and structured manner. Everything from white papers to corporate memos to the product features listed on the side of a box can be considered tech writing. It is a very important field, because without the ability to properly communicate ideas and instructions internally and externally, a company has no chance at maintaining organization or selling a product.
You might think that technical writing isn’t that difficult. After all, when it comes to something like writing a user guide or product manual, all you have to do is create a set of step by step instructions on how to perform a certain task. We read and consume instruction manuals all the time in order to do things like construct a shelving unit from Ikea or program a microwave to get that darned clock to stop flashing and display the correct time for once. With the average consumer’s familiarity with technical writing, it shouldn’t be hard to reproduce, right?
Step 1: Do Your Research.
Well, It may not be as easy as you would think. Something that we rarely consider while reading technical writing is how the person who wrote the instruction manual knew to perform these steps. Often times, creators and designers don’t have time to sit down and document every aspect of their product. They may have notes, but they aren’t always clear or well worded, and might not even be complete thoughts. Translating these notes into understandable directions takes more time than you may think, and sometimes requires that the writer experiment with the product themselves in order to fully understand how it works. Testing, fact checking, and researching are huge components of the process development phase, and can end up taking more time than the actual writing itself.
Step 2: Watch Your Tone.
Once that procedure has been tested and written out in a legible format, the next thing to consider is tone. The context of the piece is extremely important to determining the appropriate type of voice that should be used when conveying information. For example, when instructing a class, teachers generally address their students in the formal, plural you. This makes sense, as they are directly addressing an audience in front of them. However, instruction manuals tend to be written in a passive voice. It seems counter-intuitive to Americans, as we are taught from at least high school to write essays and formal papers in an active voice.
So why the passive voice? It’s more formal, for starters. In technical writing, you’re not directly addressing your audience, and passive voice removes any hint of familiarity with the reader. And while support comes in more forms than ever before, as we’ve previously discussed, it’s not always the quickest or best option for a user. Thus, it’s essential to avoid writing too conversationally in order to give the clearest, most concise explanations so that the user may get the most use from the product. For these reasons, it’s important to figure out what level of familiarity with the reader you need to present, and then write to it.
Step 3: Words, Words, Words!
Striking a balance between too much information and not enough is also essential. It’s important to keep from being overly wordy. Short, concise sentences and small paragraphs are much easier to read than walls of text, and it’s doubly important when you’re attempting to follow instructions. The longer a paragraph extends, the easier it is to lose your place. Use lists and bullet points wherever possible, and try to include meaningful diagrams or screencaps to help orient a potentially confused reader and break up the text.
Conversely, you don’t want to include too little information. A technical writer should never assume that the user knows as much as they do. Instruction manuals are not generally written just for experts in a field, but for those who are unfamiliar with a product. As such, it’s important to make notes about any complicated or involved process that might require you to make assumptions about the system. If more in-depth explanations are needed, make use of appendices to allow for quick reference to a topic that may be intuitive to some but not to others.
Writing a instruction manual isn’t as easy as following the directions in an instruction manual. When you already know the steps, the way to perform a task or use a product seems obvious. But technical writers don’t always have that privilege. They must research and experiment in order to build a functioning document from the ground up. It’s not insurmountable feat, and finishing off a document comes with a sense of pride and satisfaction.
I have a cousin who is interested in learning more about technical writing and possibly pursuing a career in IT with it. However, I have noticed that she uses long paragraphs in her writing instead of short ones. How long would you say would make a paragraph too long?
Hey Katie, thanks for taking the time to comment!
This is a really good question with a bit of a subjective answer. A good rule of thumb is that a paragraph should be about three to five sentences long. Of course, some sentences can go longer than others, so personally speaking, if I notice a paragraph has extended past 8 lines of text on a full width page, I cut myself off. Any paragraph that takes up more than a quarter of the page is definitely too long, unless your name is J.R.R. Tolkien or G.R.R. Martin (in which case, I still think it’s too long, but you can get away with it because you’re a famous high fantasy novelist).
I hope that helps, and let me know if you have any further thoughts or questions on the topic.
Thank you so much for your question. Paragraph length can be a tricky thing to manage in the world of technical writing because it can depend greatly upon the type of document that’s being created. For example, if you’re writing up an instruction manual, you want to minimize paragraphs as much as possible, and keep to bullets and numbered steps for the majority. If you do have to add explanatory text (which can happen), it’s best to keep it to 2-3 sentences max. It’s also important in these cases to use formatting to ensure that important warnings and notes don’t get glossed over. When it comes to larger, more narrative-based documentation (such as a design doc), it’s generally still safe to follow the high school rule of 3-4 sentences.
The most important thing, however, is to make sure that paragraphs (regardless of size) revolve around a central idea. You want to break whenever you’re moving on to a different topic, getting into a deeper explanation on a certain point, or moving down a list of items within a main theme. Keeping each paragraph to a single idea helps readers break up the text in understandable blocks, and the white space gives them a moment to pause, absorb what they’ve just read, and move on.
Best of luck to your cousin, and happy writing!