Emails that are one long paragraph, instruction manuals filled with confusing terms, that rambling text message from your friend where she never mentioned exactly where everyone’s meeting up: these are all examples of bad technical documents. And by technical documents, I mean pretty much all writing other than creative writing: proposals, blog posts, product descriptions, restaurant menus, driving directions, building signage, event flyers… Basically any writing with a job.
With any technical document, you’ve got a bunch of information you need to get into the brains of an audience who doesn’t have the time or the patience to listen to you ramble on. But just a few basic concepts can significantly improve your writing, make it easier to read and help your audience get the information they need.
Make Your Documents Usable
The first way to significantly improve your technical documents is to stop thinking of them like beautiful short stories or dry term papers or meandering conversations. Technical documents are tools meant to be used by an audience. So you have to make them usable.
Use a Scannable Style
One of the best ways to make a document usable is to consider how well it scans. And by scan, I don’t mean like through a copy machine. I mean, how easily can a reader pick out information by quickly glancing through your document?
Stories are read, but technical documents are scanned. Some ways to help your audience do this is to use descriptive headings, short paragraphs and bullet points where appropriate. The more digestible chunks you can break your document into the better.
Also, the best studying tip I’ve ever received was, “If everything is highlighted, then nothing is highlighted.” If your document is filled with bold, underlining, highlighting, large font, small font, and on and on then it isn’t helping anyone. Everything screams ‘Important’, and therefore nothing is important. It just looks like a jumbled mess. Show restraint, and your patience will be rewarded.
Use the Inverted Pyramid
An Inverted Pyramid style of writing can help readers scan your documents as well. The Inverted Pyramid is a journalistic approach to writing where you compose a piece by beginning with the most broad piece of information, and then slowly getting more narrow in focus as you continue. Just like an upside-down triangle. Get it? By doing this, you make it easier for the reader to find the important information, because you’ve broadly defined each chunk at the start.
When thinking about usability, you must remember you are providing a service to an audience. So don’t ever blame them for ‘not getting it’. If someone uses your document incorrectly, that’s your problem to solve, not theirs.
Make Your Writing Modular
Ultimately, usability and scannability culminate in modularity. Something is modular if it can be broken down into key components and then recombined in a new way. For example, Lego structures are modular, because you can break them down to the blocks then rebuild them in a different format. A long piece of writing should work just like this. Each piece works independently. And it works as part of the whole. And it works regardless of what order you put those pieces in.
The more headings and subheadings you use, the easier it is for readers to pick through your writing and find the parts they need the most. But that’s not all. You also need to do the same with your paragraphs. If I’m skimming through a long document, I should be able to stop at any paragraph, read the paragraph and understand a complete thought—without needing to read the paragraph before or after for context. Each paragraph serves as its own nugget of information I can munch on at my own pace.
If you need to see an example of modularity, look no further than Wikipedia. It’s the greatest example of a technical document I have ever seen. Every Wikipedia article is composed of sections and paragraphs that can be read independently without reading any other information on the page. And each paragraph covers whole and complete bite size portions of the greater topic. In other words, it’s modular.
Make Your Documents Consistent
Part of being modular is being consistent. Consistent writing gives the reader a lower learning curve to understanding what they’re reading. The writing becomes more accessible, and it helps readers attain the information with as few obstacles as possible.
Use Consistent Schema
A schema is basically an established structure that people use to organize information. It’s a system of assumptions we use to get through life without being overwhelmed with new information. For example, McDonald’s has a certain way of working: You drive up to a big illuminated menu to place your order. Then you drive up to a window where you pay for your food. Then you drive up to another window where someone hands you your food. And then there’s usually a trash can where you can throw out the food you left in your car from the last time you were there. This is called a schema. It’s the way we expect all fast food restaurants to work. And when they don’t work like this, we get confused.
Your writing should be the same. Follow the established design rules of your genre. Restaurant menus usually work in a certain way: appetizers are at the front, then entrees and then sides. Often, drinks are on the back of the menu along with desserts. So stick to that. Don’t get creative with the menu. It has a job to do. Get creative with the food. If you establish a schema, and stick to the rules of that schema, it will make your writing much easier to read.
Use Consistent Terminology
Beyond using a consistent structure, design and style, you should also be consistent in your use of words and terms. When you’re comfortable in an environment, or well-versed on a topic, it’s easy to slip into the lingo of your trade. But don’t forget your job is to appeal to an audience that may not be as well-versed as you are. Remember that when you write a technical document, you are exposing your audience to new information. So you must assume some level of ignorance.
Look to legal documents as an example of how to incorporate terminology into your documents. If you flip through any dictionary, you’ll see that most words have multiple definitions. According to Merriam-Webster, a sham is both ‘a trick that deludes’ as well as ‘a pillow covering’ 1. Words have many connotations depending on the context we use them in. In fact, that’s exactly how puns work.
But in contracts, agreements and other legal documents, you will often see a Defined Terms or Definitions section near the beginning. This section defines the specific way a word will be used. And then that word is used exactly as defined throughout the document. Lawyers do this to avoid the ambiguity that comes from audiences defining terms differently.
Make Your Writing Simple
The next step after using consistent language is to use simple language. The goal of writing is to get an idea across. So always focus on the most efficient way to do that without being a slave to terminology and lingo. Words are a means to an end. In “Politics and the English Language”, George Orwell says:
In prose, the worst thing one can do with words is surrender to them. When you think of a concrete object, you think wordlessly, and then, if you want to describe the thing you have been visualising you probably hunt about until you find the exact words that seem to fit it. When you think of something abstract you are more inclined to use words from the start, and unless you make a conscious effort to prevent it, the existing dialect will come rushing in and do the job for you, at the expense of blurring or even changing your meaning. 2
The goal of technical documents is not to show off how much you know or quickly get through a half-assed description without considering your audience. The goal of technical documents is clear and accessible communication.
Use Passive Voice Sparingly
I would also suggest using passive voice sparingly. In a typical sentence, the subject of the sentence does the action. For example: ‘I drove into the tree.’ But a passive sentence works in reverse. The subject of the sentence has the action done to it. For example: ‘The tree was driven into by me.’ You can usually tell if a sentence is passive if it uses some version of the verb to be in it.
Despite what some grammar apps will tell you, passive voice is not evil. In other languages, it’s much more common. And in science writing, it’s often preferred. But in common English writing, passive voice often leads to longer and more convoluted sentences. Passive sentences require more thought to understand, because they are essentially written backwards. In short sentences, this isn’t a big deal. But in longer sentences, it can really bog down the flow of reading. Instead, keep your sentences active, straightforward and simple.
Remember, technical writing is rhetorical writing. You want your audience to do something, and so you wrote out information to help them do so. Therefore, your focus as a writer should always be on the audience and how you appeal to them.
- “Sham” | Merriam-Webster
- Orwell, George | “Politics and the English Language” | Horizon | 1946