January 2014
By Leah Guren

Image: © Denis Iachimovschi/ 123rf.com

Leah Guren is the owner/operator of Cow TC, located in Karmiel, Israel. She has been active in the field of technical communication since 1980 as a writer, manager, Help author, trainer and usability consultant. Leah is a popular speaker at technical communication conferences around the world, a published author iand an Associate Fellow of the Society for Technical Communication (STC).


leah[at]cowtc.com
www.cowtc.com


 


 

Minimalism in documentation

Minimalism is the idea that less is more; that fewer ďbells and whistlesĒ is better; that good design leads to intuitive, natural, and instant use. How can you adopt minimalism in your documentation?

John Carroll, the leading proponent of minimalism in software design, introduced the idea of progressive information disclosure Ė the process of showing information based on what the user selected, rather than showing everything at once. Carroll insisted that a product should be so intuitive that people could instantly use it without having to read a single page of the documentation.

What is minimalism?

Minimalism in documentation is the idea that:

  • you donít need to document every single aspect of most products;
  • users can play with the product and discover functions on their own;
  • fewer words on a page (or screen) improves navigation (the ability to find content);
  • writing in a simple, straight-forward language improves comprehension.

Minimalism is more than removing fluff. Fluff comes in many forms: unnecessary words (saying something in 20 words instead of 5), overly complex words, needless repetitions, pompous or unnecessarily formal writing, or vague writing (for example, a sentence that can be interpreted in multiple ways, perhaps because of the inherent ambiguity of English, or a modifier that canít be quantified). You can cut out words and still have fluffy writing; and you can have fluff-free writing that isnít minimalist.

How did we get here?

Look at any technical product documentation from 30 years ago and you are likely to discover long, complex sentences and dense blocks of text with very little visual design. Inexperienced technical writers often took input from the SMEs (subject matter experts, such as engineers, programmers, or other developers) and turned it into ďcorrect English.Ē The writing resembled verbose, pompous research papers, rather than useful tools designed to help the user successfully use a product.

In the mid 1980s, a new breed of technical specialist began to emerge Ė the usability expert. These people looked at information from a completely different perspective. Instead of focusing on product features and technical details, they looked at how people actually used products. Jakob Nielsen, William Horton, Jared Spool, and other pioneers in this field significantly changed the way we analyze, write, and even structure information.

One of the most compelling studies was the now-famous example from Sun Microsystems back in 1994. Jakob Nielsen, at that time an engineer at Sun, was involved with the development of SunWeb, Sunís intranet. Nielsen conducted usability testing on the initial prototype of the intranet, then cut 40 percent of the text and retested. The results were astonishing. The overwhelming majority of users found the new version to be not just better, but more information-rich. The message was clear: too many words hide content, confuse meaning, and significantly impair navigation.

As the usability movement grew, more and more data emerged confirming these findings. Excess words are deadly! They make it harder for people to use products safely and effectively. And, after all, helping people use products safely and effectively is the core charter of our profession!

At the same time, the business argument for minimalism emerged. Reducing a bloated documentation suite of 1000 pages by even 10 percent meant significant savings in localization, printing, and production costs. The improved documentation usability led to fewer calls to tech support, which meant additional corporate savings. In short, everyone won.

It was a revelation to many professional technical communicators and editors to realize that there was no legal, moral, or ethical obligation to explain every single bit of minutia about a product. As a profession, we now understand that there is a price to pay for every extra word on the page and every extra page in the manual. Documentation minimalism became the accepted trend. Major players, such as Microsoft, switched to minimalism in their documentation. Gone were the big manuals, replaced by hundreds of short, concise Help topics.

The good, the bad, and avoiding the ugly

The good: when minimalism works

Minimalism works brilliantly when you just need a quick reminder about how to do something, where something is, or what something is for. Want to reset the clock in your carís dashboard? You donít need to read long paragraphs explaining the multi-function button combinations; you just want to know what sequence to push.

Any kind of just-in-time documentation works best when it embraces minimalism. Slivering information into progressive disclosure (just what you need to know for this step, this page of the wizard, this part of the process, etc.) helps users focus on the immediate step without the distraction of low-level details or high-level process flow.

Minimalism is also the best approach for interface: if you want to label part of the graphical user interface (GUI) or the physical product interface with text, minimalism works well.

The bad: when minimalism fails

There are several scenarios when minimalism fails:

  • If users consistently show poor compliance, it might be because they donít understand big conceptual issues, such as the internal mechanisms of the product. For them, adding theory of operation and other background content, which is not usually part of true minimalist documentation, becomes very helpful.
  • The product is unlike anything else. Again, in this situation, users lack the correct mental model to understand the product, and therefore may make usage mistakes.
  • A diverse audience but no option for multiple documents. In this scenario, you need to add extensive layering and sometimes even repeat information to support the needs of a mixed group of users.

Avoiding the ugly: finding a compromise

In many cases, you need to find the middle ground. While minimalism fails in some situations, the solution is not to veer back to fluffy, wordy, overly long documentation. The answer is to slowly add in words that provide context, clarify conditions, provide motivation, and improve usability and user compliance.

Consider signposting elements, such as headings. They often are greatly improved by the addition of a word or two. For example, the heading:

Guidelines

communicates a lot less than:

Guidelines for Selecting Printer Settings


The price of those extra four words is insignificant when compared to the improved signposting and usability.

The editorís challenge

Recognize your nature

All of us are editors. Even if you are a writer, rather than a professional technical editor, you still need to be able to review your own work and to provide editing support for others in the team. Therefore, the best starting point is to recognize your own style: are you fluffy or overly minimalist?

Tips for the fluffy

Do you tend to overwrite? No fear! Get the ideas down. Let the writing flow. Donít hold back. Then, assuming that the structure is logical and correct, go back and start editing ruthlessly.

  1. Run the text through a readability calculator. Various algorithms, including the Gunning Fox index, the Flesch Kincaide Grade Level index, the SMOG score, and the Coleman Liau index, all tell you how readable your text is. Most calculate the number of years of education a reader needs to comfortably understand the text. They look at sentence length, word length, use of passive voice, and more. A good all-in-one online calculator (such as the one listed in the references below) gives you all scores. These metrics are necessary as a starting point. If you donít know where your text currently scores, how will you know if you have improved it?
  2. Target long sentences: break them down, simplify them, shorten them.
  3. Target long words: find simpler ways of expressing the same idea.
  4. Look for unnecessary content: do you really need to tell users about the four different ways of accessing a feature?
  5. Look for unnecessary repetition: if something isnít essential for a critical workflow, you donít need to repeat it. You can offload the information to one location and then cross-reference it.
  6. Look for content that is there only because you are afraid to delete it, even though you have no idea what purpose it serves. Dump it or offload it to an appendix (see Junk drawer, below).

Tips for the terse

Do you tend to underwrite? Do you struggle figuring out what to write or understanding why you need to write something? If you are overly terse, you may not be seeing the missing logical connections. Things that seem obvious to you may be conceptual jumps from A to D; users need to be led through B and C.

  1. Do usability testing. Have someone who matches a persona read what you wrote. Have the person explain it back to you. If they canít, then you are probably missing context.
  2. Look for the why, not just the what. Telling users what something is doesnít help them decide whether or not to use it; telling users how to do something doesnít help persuade them why they should do it.

Perform triage

Remember that not all content is created equal. We, as technical communicators, have the responsibility of analyzing and filtering information that we receive. Just because an SME said so doesnít make it true; and just because something is true doesnít make it necessary. Therefore, examine information critically and place it in the correct category:

  • Essential
    Essential information is content that is necessary for someone to use the product safely and effectively. This includes clear, straightforward procedures for the most commonly needed tasks in the user workflow, plus essential background information about the product and its interface.
    Another type of essential information is anything that must be there because of regulatory, compliance, legal, or certification issues. Many compliance rules donít help improve the usability of documentation, yet if you violate them, you risk having the entire product rejected. For business reasons, anything mandated by regulatory, compliance, legal, or certification bodies must be followed, whether or not it actually helps users.
  • Value-added
    Value-added information is content that, while not essential, adds something useful. It can be the layering that provides context, improves user compliance, helps establish a correct mental model, helps novice users, adds skills for advanced users, and does anything to improve the readability and navigation of a document.
  • Junk drawer
    Junk drawer information is anything that has no real value. Often, this is legacy information from previous versions, things that the SMEs think are interesting, details about unused features, background information that doesnít translate into necessary knowledge, and more.
    When dealing with this kind of information, it is usually safe to offload it from the main workflow. For example, turn it into reference content, such as an appendix. If you are truly brave, delete it. In most cases, users never notice the loss of unnecessary information!

Permanence and the learning curve

One common problem is writing for the first-time user who knows nothing about the product. Yes, you need to include information appropriate for this type of user in our documentation, but be very careful about any information that has permanence. For example, text that appears as part of the product interface may be quite helpful the first time the user tries to figure out what to do, but can be very annoying after the second or third usage. Think about text labels on interface elements, text on appliance front panels, and the level of detail in task and descriptive topics.

Donít forget to test!

Any major change in documentation requires testing. You need to know that your edits are making the documentation better. The only way to do this is to have some benchmark against which you can compare the new version. Therefore, before attempting any complete rewrite of content, start by performing documentation usability testing on the existing version.

To do so, start by learning the basics of usability testing, including defining your personas, identifying specific tasks for testing scenarios, setting up your test environment, and finding testers. Make sure that you know how to run the actual tests and what to do with the results.

After rewriting the first draft, repeat the testing with new testers. Compare the results. Look for:

  • tasks that had a higher completion rate or a faster performance time
  • reduced time spent searching for information
  • any decrease in problems or questions from the tester

Conclusion

No matter how much legacy documentation you have, it is never too late to start reducing fluff and moving towards minimalism without, of course, going too far into unhelpful terseness. Start small with one task, one chapter, or one Help topic. Measure your results and then extrapolate to show value, both in savings and improved usability. This value is the way you persuade management to allow these changes across the board.

References and resources

Page 1 from 1
1
#1 Steven Swanson wrote at Thu, Jun 26 answer homepage

Good stuff Leah! "Brevity is the soul of wit" - Shakespeare