Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
Back in the Dark Ages of Tech Writing, minimalism might have meant leaving out definite and indefinite articles, you know, ‘the,’ ‘a,’, and ‘an.’ After all, we wanted to sound all technical and using articles made the instructions and information way too understandable, not technical at all.
Being technical also meant never using second-person singular. It just was not done. Too friendly. This, of course, resulted in passive voice instructions that tended to distance the user from the action. That kind of technical writing was also wordy and confusing. Oftentimes you couldn’t tell who was doing what to whom and how.
The current thinking is minimalist writing, to be more straightforward, to write all that is needed for a chunk of information and no more than is needed. And, to write it in a clear, direct active voice.
You would think writing minimally would be easier. I mean, you are trying to write fewer words but that is so not the case. When you write minimally, you have to determine over and over whether this word or that phrase is necessary to the information you are trying to impart. It is like cleaning out a closet. You can’t do it in one pass at least not until you have written the same types of information multiple times and really start to notice where you have a tendency to pad the text.
We all know about word weeds. You know, using “in order to” instead of just saying “to.” I can provide whole lists of those. But what about the sneakier sort of text padding?
In the old days, we would set up the context of this bit of information with some text about the ’68 Impala and then maybe start the steps with an introductory phrase, “To change sparkplugs on a ’68 Impala, perform the following steps,” and then proceed with Step 1. We may even tuck some special information between steps 3 and 4 about which sparkplugs to buy according to price, longevity, and specific circumstances. All very reasonable.
In minimalist authoring, each topic is a single set of information and would not allow for anything but that set of information.
So in our topic of the previous paragraph, the minimalist would create an overall document, “How to Maintain a 1968 Chevrolet Impala.” This document would begin with concept-type introductory sentences we thought necessary to the reader’s understanding of what kinds of topics are in the document.
Somewhere within that overall document, we would provide a subtopic called “Changing sparkplugs.” We already know we are working on a ’68 Impala so we don’t need to repeat that bit of information. We also do not need the “To change the sparkplugs,” introductory statement. That information is in the topic title. We can immediately start with Step 1. Topic title then Step 1, simple.
Any thoughts we have on sparkplugs or tools that are not directly related to the task itself, go into a Reference topic. This reference topic could be a table of sparkplug brands and which ones to use under various conditions. In addition, that table would be in its own topic, maybe following the procedure or maybe in a reference section with a cross-reference from the procedure.
Voila! You are now writing minimally.
However, as I said, you are not done. Continue writing other tasks about Chevy maintenance, all of them and only the tasks, as individual topics. Set all reference information aside in another file that you will sort through later when you are writing reference topics.
When you have finished writing all the task topics, come back to the first one. You will no doubt find that you can extract even more words from the task. Not only that, you will probably find that you only need one introductory paragraph for all the tasks of a certain type instead of an introductory sentence for each of them. Maybe you find that you now want to have two concepts for maintenance: “Maintenance under the hood” and “Body maintenance.”
See, when you write topics only, you can change around the flow of the document at any time without having to do a complete rewrite. This is also part of writing minimally, topic-based authoring.
When you are finished with all the tasks, notice that your reference topics almost write themselves. All the reference information is in one place so you reduce the chance of redundant information. You do not repeat the reference information in each topic that requires the information. You write each reference piece once and refer to that information from any and all topics that need that information.
All of this is simpler and less easy than I have made it sound but, with practice, writing minimally begins to become part of your writer DNA.
Rules for going minimalist
Okay, so it is not just writing minimally. Minimalism has rules. Well, they are more guidelines than rules but you should heed them nonetheless.
- Use no more than 7 steps in a procedure.
- Tell the story with pictures, if possible.
- Keep sentences short and to the point.
- Ensure that each step in a procedure contains only one action. That includes steps like, “Select the appropriate value and then select Save.” Don’t do that. This should be two steps.
- Ensure paragraphs are no more than 10 lines long, even if this means a somewhat arbitrary paragraph break.
- Use active voice. If writing in active voice is not natural to you, don’t worry. You can go back and fix your passive voice boo-boos after you have all your main thoughts on the page. That’s what I do.
I sort of fell into technical writing sideways, working as a business analyst for Ernst & Young. However, of all the careers I have had, and there have been many, I love tech writing the most. To read more about my love for technical writing, visit The Technical Author. For more on writing content minimally, go to Golden Rules for Content.