It’s difficult to understand exactly why technical writing is often mostly gobbledegook. But it seems that when people write, for example, regular emails, those emails are often short and concise. Yet, those same writers, when writing technical documents, often end up writing gobbledegook. Sadly, this phenomenon seems to also be true with (non-trained) technical writers. Unfortunately for their audience (readers), technical writers are often document “assemblers” and take for granted the “boilerplate” and other poorly written text they receive and sometimes even write.
Most technical writing problems fall into several readily-noticeable categories. Below, we list those categories (see: “Change this” and “To This:”) to show how to improve otherwise gobbledegook writing.
Outline: get organized —> Don’t write linearly.
Modern word processors present a page metaphor. This metaphor encourages us to jump in and to write linearly with little if any up-front organization. While writing linearly may be acceptable for a short letter or email, technical writing demands planning. To help plan, consider using an outlining tool or at least a writing environment that includes, or can import, outlines. Having this outline roadmap of what you want to say is critical as you dive into the writing details. Said another way, an outline is your roadmap and will help keep you on track.
(Note: Programmers who “jump in and start coding” with no preparation often end up with buggy programs, difficult-to-maintain code, or, worse yet, never actually finish their tasks.)
Avoid boilerplate gobbledegook
Many companies have so-called “boilerplate” text. This text is often full of unnecessary text, jargon, and other gobbeldegook to make their documents appear “professional” and consistent. Some companies believe more-pages-is-better (wow, look at all this text we can present to you!). Most of this boilerplate text is so poorly written nobody reads it. Therefore, if boilerplate text is required, and if you’re allowed, write that boilerplate text yourself or modify the jargon-laden existing boilerplate text so that it fits your writing project.
Know your audience and write for them
One of, if not the, the most important issues you face is writing to the correct audience. For example, if your audience is management staff, but you’re writing about a program’s algorithms and threading assumptions, then you’ve clearly missed the mark. Conversely, if you’re writing to the technical staff, but you are focusing on corporate objectives and other strategic goals, you probably also have missed the mark. Therefore, one of the first steps to take is to figure out who your audience is and then write to them.
Below are a few examples of typical technical writing issues…
Avoid redundant expressions
Avoid redundant expressions like “in the area of” or “green in color”. Redundant expressions unnecessarily tell us something we already know.
Change this: “He is experienced in the area of technical writing.”
To This: “He is an experienced technical writer.”
—
Change this: “The purpose of this document is to outline the corporate objectives.”
To this: “This document outlines the corporate objectives.”
(Note: Funnily enough, you’ll see redundant expressions even on sites that are supposed to help technical writers write better.)
Avoid ambiguous antecedents
When you start a second sentence with the word “It”, or other pronoun, it’s up to the reader to puzzle over what actual noun in the previous sentence “It” is referring.
Change this: “Many students use a computer to help them write a paper for an exam. It is often stressful.”
(Does “It’ in the second sentences refer to “computer”, “paper” or “exam”?)
To this: “Many students use a computer to help them write a paper during exams. Writing a paper is often stressful.”
Avoid passive voice
Passive voice has no actor and lacks action or interest.
Change this: “The proposal was written by the team.”
To This: The team wrote the proposal.
Because active voice has a subject acting, active voice is easier to read.
Avoid weak verbs
Drop-kick weak verbs like “provide”, “perform”, and similar. These verbs add nothing to technical writing. Instead of these verbs, use more descriptive verbs.
Change this: “The work to be performed in the area of task analysis will be completed by June 1.”
To this: “The team will analyze tasks by June 1.”
Which of the two above was easier to read for you to immediately grasp?
Use short sentences
Keep your sentences short. Don’t use commas, semi-colons, and other punctuation to justify longer sentences.
How to Be a Better Technical Writer (and Have Your Readers Better Understand What You Write)
Write simply. Use simple English.
Avoid Elegant variation:
When writing, avoid using synonyms to keep from repeating a word — even if that original word is the right choice.
The tendency by some writers is to look up in the thesaurus some synonym for a word to avoid using the same word over and over.
Simple language is always appreciated by the reader.
Change: “The use of software to write software modules has increased productivity. Modular utilization of software has also cut costs.”
To this: “The use of software to write software modules has increased productive. Modular use of software has also cut costs.”
In other words, don’t use “utilization” just to be different from using “use” the first time. “use” is fine in both sentences. (The examples above also have redundant expressions that the writer could have better worded.)
Avoid needless word complexity. For example, rather than writing “utilize”, try “use” (And similar).
Avoid long variants of verbs.
Include graphics or report samples to back up text
The old saying that a picture is worth a thousand words is applicable when clarifying complicated technical content. For example, when describing a complicated system output, such as a report, consider including a report output sample. Similarly, when describing a graph, show what a perspective graph would look like.
Including graphical output will help you get better feedback from users and from current and prospective customers. There are many tools that will help you prototype system outputs for reports, proposals, and for other technical documents.
Conclusion:
Writing for most people is difficult. Keys to success include:
- Getting organized
- Doing your research
- Outlining your writing to stay organized
- Writing simply
- Knowing and writing for your document’s audience
- Revising as necessary
- Reviewing with others
Writing is something we all do every day. Fortunately, becoming a better technical writer is not difficult. Strive to keep your writing simple with short sentences. And, use simple English. By making just a few adjustments to your technical writing, you will make it easier for your readers to better understand what you are trying to convey.
Enjoy!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please read our disclaimer available from our home page