Looking for something?
By Michael Harvey, STC Fellow
When you read a technical document, how many pages must you turn before you can do real work? I posed this question while evaluating a document that I had written as an exercise in the workshop “Minimalism: Creating Information People Really Need.” The number should be few. Unfortunately, my answer was 76. Or maybe it was 41. Just from the exercise, I could tell that I would benefit from what I was about to learn.
Based on the research of John M. Carroll at IBM’s Watson Research Center, minimalism is text-based learning that encourages exploration of technology rather than rote learning. To apply minimalism to writing, use fewer words in action-oriented text. Cut back on descriptions. Eschew useless information. Useful information shows rather than tells, and allows a reader to act. It eliminates ROT – the redundant, outdated, and trivial.
An important goal of minimalist writing is to create information tools rather than content containers. The best way to achieve this is to optimize content for search; organize topics around user roles and activities.
This does not mean that we completely abandon descriptive or conceptual material. Instead, we allow readers to opt-in to it, providing it in appendixes. Motivated readers will opt-in whenever they think they will get something that they want. Similarly, chapter tables of content are useful only when they provide the reader a workflow. To better understand this principle, class participants were encouraged to set up TOCs as if they were quick reference cards. In other words, write TOCs with verbs to guide readers to the salient task covered by the section or chapter.
What about screenshots? Minimalism recommends using screenshots only to show cause and effect, progression, or contrast. If there is no instructional purpose served by a screenshot, get rid of it.
In this contest, the first or second team always wins and the fourth team always has the hardest time. This clearly demonstrates the practical power of illustrations, especially when they are paired with step-by-step instructions.
The <xref tag> resolved to the heading “Assigning Roles to Nodes.” So that meant that in the finished document, this appeared:
No one needs that kind of repetition. So I changed it to the following:
I had also provided an example with step-by-step information. In an overview, I had provided a numbered list before the next section:
After this list, my section headers were:
and so on. Applying minimalism, I eliminated the numbered list altogether.
I was also able to apply minimalism in a more direct way. In one of my User’s Guides, I had several sections in an early chapter that described how to explore the cubes that you create with a certain SAS procedure. In a later chapter, I provided a complete example of creating and exploring a cube. Applying minimalism, I removed those descriptive sections from the early chapter, and retitled the later chapter “Working with Risk Explorations: An Example.” After all, I was essentially covering the same material in both places. I kept the example because it showed in a direct, task-oriented way, most of what the sections in the early chapter had described. What was not covered in the example was covered by EUA or could be intuited by exploration of the user interface (UI). I eliminated at least 20 pages.
So how can we reduce the number of pages that we must turn before we get to a real task? A simple change in mindset might be the best first step. In a recent interview in the STC Intercom, John Carroll himself suggested that we think of our readers as “learners” rather than “users”. He said that “(readers) need to act, they need to be engaged” as they learn. As we write, “we have to exert a certain amount of self-control, empathy, and...user-testing...to make sure we don’t lapse into decoration and obstacles” to this learning. We should not force our readers to read more than we would want or need to read.
Michael Harvey can be reached at mtharvey at yahoo dot com.
Michael Harvey
Based on the research of John M. Carroll at IBM’s Watson Research Center, minimalism is text-based learning that encourages exploration of technology rather than rote learning. To apply minimalism to writing, use fewer words in action-oriented text. Cut back on descriptions. Eschew useless information. Useful information shows rather than tells, and allows a reader to act. It eliminates ROT – the redundant, outdated, and trivial.
Writing by Minimalist Principles
The four minimalist writing principles are:- Choose an action-oriented approach. Emphasize tasks before you explain concepts and ensure that tasks follow a real workflow.
- Focus on users’ real goals. Anchor everything that you write in the task domain rather than the tool domain. For example, do not lead with tabs or menu items (“the Home tab enables you to change fonts”); lead with what you can do through them (“Change fonts through the Home tab”).
- Support error recognition and recovery. Provide steps to recover from mistakes whenever errors are likely to occur, and provide carefully labeled troubleshooting steps within procedures.
- Support information access. Readers view technical content as a series of answers to questions that they have about the product. Craft your headings, labels, and topic sentences accordingly.
Readers view technical content as a series of answers to questions that they have about the product. Craft your headings, labels, and topic sentences accordingly.
This does not mean that we completely abandon descriptive or conceptual material. Instead, we allow readers to opt-in to it, providing it in appendixes. Motivated readers will opt-in whenever they think they will get something that they want. Similarly, chapter tables of content are useful only when they provide the reader a workflow. To better understand this principle, class participants were encouraged to set up TOCs as if they were quick reference cards. In other words, write TOCs with verbs to guide readers to the salient task covered by the section or chapter.
What about screenshots? Minimalism recommends using screenshots only to show cause and effect, progression, or contrast. If there is no instructional purpose served by a screenshot, get rid of it.
The Practical Power of Illustrations
The class participated in a timed contest among four teams to assemble Lego pieces. My team’s instructions consisted of a progression of illustrations. It appeared that we were assembling some type of car. My team did not finish first, but afterwards we found out why. The exercise was rigged!- The first team got step-by-step instructions with illustrations
- My team got illustrations without step-by-step instructions
- The third got step-by-step instructions without illustrations
- The fourth team got a narrative with a lot of irrelevant details, no illustrations, and no steps.
In this contest, the first or second team always wins and the fourth team always has the hardest time. This clearly demonstrates the practical power of illustrations, especially when they are paired with step-by-step instructions.
How I Applied What I Learned
I found opportunities to apply minimalism to my writing almost immediately after finishing the workshop. For example, I had written the following passage in one of my documents:For more information about assigning roles to nodes, see <xref tag>.
The <xref tag> resolved to the heading “Assigning Roles to Nodes.” So that meant that in the finished document, this appeared:
For more information about assigning roles to nodes, see “Assigning Roles to Nodes” on p. 26.
No one needs that kind of repetition. So I changed it to the following:
For more information, see <xref>.
I had also provided an example with step-by-step information. In an overview, I had provided a numbered list before the next section:
Follow these three steps to accomplish something really important:
1. Do thing one
2. Do thing two
3. Do thing three
1. Do thing one
2. Do thing two
3. Do thing three
After this list, my section headers were:
Do Thing One
<text>
Do Thing Two
<text>
<text>
Do Thing Two
<text>
and so on. Applying minimalism, I eliminated the numbered list altogether.
I was also able to apply minimalism in a more direct way. In one of my User’s Guides, I had several sections in an early chapter that described how to explore the cubes that you create with a certain SAS procedure. In a later chapter, I provided a complete example of creating and exploring a cube. Applying minimalism, I removed those descriptive sections from the early chapter, and retitled the later chapter “Working with Risk Explorations: An Example.” After all, I was essentially covering the same material in both places. I kept the example because it showed in a direct, task-oriented way, most of what the sections in the early chapter had described. What was not covered in the example was covered by EUA or could be intuited by exploration of the user interface (UI). I eliminated at least 20 pages.
Taking a Minimalist Perspective
One of the most useful insights into minimalist writing that I gained was through an offhand contrast made by the workshop instructor. With fiction, we want to be able to say “I could not put it down.” With technical communication, we want to be able to say “they could put it down.” What we write is a means to a practical end. The less our readers have to mull over our words, the better.So how can we reduce the number of pages that we must turn before we get to a real task? A simple change in mindset might be the best first step. In a recent interview in the STC Intercom, John Carroll himself suggested that we think of our readers as “learners” rather than “users”. He said that “(readers) need to act, they need to be engaged” as they learn. As we write, “we have to exert a certain amount of self-control, empathy, and...user-testing...to make sure we don’t lapse into decoration and obstacles” to this learning. We should not force our readers to read more than we would want or need to read.
Michael Harvey can be reached at mtharvey at yahoo dot com.
Top of page
Staff and authors:
