Technical content differs greatly from other forms of writing. Its aim is generally to provide instruction about a subject to help users solve problems. Because technical writing has such a unique, defined goal, good technical writing adheres to specific guidelines. Let’s look at some of the most important things to avoid when writing technical documents.
1) Vague Language
How long is a “short time?” How much is “a significant amount?” Vague descriptors like “short,” “significant,” “later,” “heavy,” and “many,” to name only a few, are open to interpretation and therefore ambiguous. Moreover, these kinds of terms are relative across time: what may have been considered a “short time” 35 years ago may very well be judged a “long time” in the future. Advances in technology can render a tech document that uses such language obsolete, so always try to be as specific as possible.
2) The Passive Voice
The active voice is stronger and more direct than the passive voice. For example, it is better to say “Use your account information to log in,” than “Your account information is used for logging in.” The active voice is usually clearer and more concise. That said, there are times when technical writers will use the passive voice: for example, when the subject is unknown or less important than the object, or when the active voice implies that the reader is to blame for a situation that may be beyond their control. Consider the difference between “If you cannot boot up the system…” and “If the system cannot be booted up…”
3) Unnecessary Information
Keep your technical content short and to the point, and avoid redundancy. If it doesn’t help the user solve a problem, it needs to go. Don’t include trivial details about the inner workings of a technology or marketing language that praises it as a triumph of engineering. For example, the average consumer doesn’t need to understand routing technology in order to set up their home router, nor do they need to read pages of marketing material to be convinced that the product they have already purchased is worth buying.
4) The Future Tense
In technical content, the future tense does not have the same immediacy as the present tense. Compare “When you connect the power cable, the device will boot up automatically,” to “When you connect the power cable, the device boots up automatically.” The future tense suggests a mild uncertainty as to how things unfold. In contrast, the present tense conveys immediacy and demonstrates confidence. This matters because technical writers frequently discuss a series of actions or describe what occurs after a user performs an action.
5) Disorganization
Organization is the key to good technical documentation. Information should be easy to find and follow a logical sequence. Whether you’re describing a simple procedure or deciding on the best arrangement of chapters, an intelligent, intuitive structure minimizes confusion and provides a satisfying user experience.
6) Complex Sentences
Much of the text in technical documentation is instructional, so sentences should be kept as simple as possible. You can achieve this by using verbs instead of their noun counterparts and by writing in the imperative without using a subject. Notice the difference between “Create a connection between the two devices,” and “Connect the two devices.” Whenever possible, use the verb form and keep your sentences simple.
7) Not Using Diagrams
Technical writers pride themselves on their ability to break down complex concepts into easily-digestible words. However, diagrams not only engage readers but are, at times, the best way to communicate your meaning. A clear and well-placed diagram or illustration may mean the difference between a user ultimately solving their problem and giving up on a product out of frustration.
Creating great technical documentation that explains ideas clearly isn’t always easy. To ensure that your content is truly top-notch, be sure to contact a professional team of technical writers to guide you on your way. Good luck!
Written by Mike Lenczewski, Senior Writer at CSOFT International