Less is more: Minimalism in documentation

Many readers will be familiar with the word "minimalism" from interior design, where we recognise that fewer but well-chosen objects in the home can result in a more beautiful environment. Or they may have heard of minimalism as a lifestyle, in which freedom from excessive consumerism results in a more conscious way of living.

Minimalism in general means focusing only on what you actually want or need, and eliminating the rest. It’s based on the idea that less is more, and you can apply it to your documentation.

The principle of minimalism 

In his article on minimalism in technical writing, technical writer Mark Baker says:

“Minimalism is an accommodation to the paradox of sense making.” This means that when we make our documentation minimalist, we acknowledge the fact that users want the least amount of instruction to complete the task as possible.

Mark goes on to say “Minimalism is about minimizing the interference of the instructions with the user’s sense-making process. It is not about preventing users from ever making errors, but about helping them to recover from the errors they will inevitably make.”

The paradox of sense making was first defined by John Carroll, Professor of Information Sciences and Technology at Penn State who also coined the term “minimalism”. [1]

His work examining the learning process founded the field of minimalism in documentation. He discovered that less really is more when it comes to documentation, especially for new users.

As Carroll says: “[people] are too busy learning to make much use of the instructions. This is the paradox of sense-making.”

How to use minimalist documentation

Now we’ve got the theory down, it’s time to learn how to actually use minimalism in our documentation.

Minimalist documentation steps in at the teachable moment: when a user makes an error. When they are focused on solving the problem or completing a task, users don’t have time to wade through flowery or messy prose. Minimalist documentation makes a huge difference in helping users to succeed.

Minimalism in software design has become the norm, and in the past Jakob Nielsen has talked about Progressive Disclosure in UX design. This concept can be applied to documentation as well, and means that users don’t need to see all features right away because they would be overwhelmed.

In Progressive Disclosure, the idea that an element appears first means it has primary importance in the interface. Designers hide secondary elements away from view, but allow users to easily click a button to reveal more features. The same goes for documentation in that you only show what is necessary but allow users to explore.

It’s closely related to having a Minimum Viable Documentation and a system of triage for your documentation, as Neal Kaplan discussed in his fantastic Write the Docs talk on the subject. Note that “minimalism” (paring down to the core elements) is not the same as “minimum” (the least amount you can get away with).

There are also strong links in minimalism to the concept of plain language – using communication that is easy for your users to understand. These are all attempts at simplifying complexity in information and design, which is the task of all technical writers.

Why use minimalist principles

There is an important need to adopt minimalist principles in documentation. This approach it somewhat at odds with the tradition to aim at comprehensiveness, dispensing with usability in some cases.

While technically accuracy is important, much user documentation is geared towards learning and understanding a product. Users need to be able to understand the documentation so they can safely use the products they relate to. Using too many words actually obscures information, and makes documentation less usable.

Minimalism can work very well for deciding what documentation to produce right now, especially for technical writers working in Agile teams, See our other post on Just In Time Documentation for an explanation on how to work in an Agile manner.

Minimalism also makes sense because fewer words means lower costs in some areas such as in printing manuals and localization or translation costs. That’s not to say fewer words are easier to produce.

Minimalist documentation takes a lot of hard work to produce and requires professional technical writers to achieve. Even though it’s relatively difficult to get right initially and you must invest, minimalist documentation saves you money and time in the long run. This tends to be by reducing support requests, and fewer frustrated users churning from your product.

When to avoid minimalism

Minimalism isn’t isn’t the answer in all situations – like when we need our documentation to be comprehensive.

As technical writer Daniel Procida talks about in The Four Types of Documentation, you still need reference guides and conceptual material for a complete set of documentation.

Your users will appreciate your minimalism when it comes to tutorials. But in some cases, minimalism won’t work because users require conceptual information about your product. This is especially true for more advanced or technical users, such as developers working with APIs. That doesn’t mean you shouldn’t offer minimalist documentation, but also make sure to produce the full range of documentation required.

Many teams are also unintentionally minimalist, because they don’t have the time and resources to devote to proper documentation. Minimalism is not a reason to cut corners.

How to achieve minimalism

There are a few ways that you can start working towards minimalism in your documentation. You may be doing many of these things already, and just didn’t know that they were “minimalist”.

Write in plain language 

Make your documentation prose easier to read by writing in plain language. Write plainly by breaking down long sentences, using the shortest and simplest words you can, and writing in the active voice.

It also helps to use a free online tool like Hemingway to edit your work for readability. It should be graded around level 3.

Every Page is Page One

Present your articles in a topic-based format and follow Every Page is Page One principles for users landing on your content.

This means that wherever your users land on your content, they won’t have to wade through mountains of other docs just to understand what that the current page is referring to.

Delete outdated or unnecessary content

Audit your knowledge base for old or irrelevant content. Remember, having too much information makes it harder for users to learn properly.

If you’re afraid of deleting content, unpublish it or store it somewhere it will be safe. That way if you ever need it, you can retrieve your archived content.

Bring your whole team on board

It can be hard to persuade other team members and your bosses to come on board when you decide that your whole team needs to move to minimalist documentation principles. This is where it helps to outline the business value and show the benefits it will have for your users.

Fight hard for your corner – you are the user advocate. Share articles from Nielsen Norman Group like this one called Simplicity Wins over Abundance of Choice. As Tom Johnson says, present your case like a lawyer to the engineers and product managers if you must, and show them the evidence of research, user feedback, and metrics.

Start small and slowly make changes that build up over time. Often conducting a small usability test that compares minimalist and non-minimalist documentation can be enough to show other people the value in paring it down to the essentials.

Over to you!

Minimalism in documentation is about getting out of your user’s way and putting them at the center of the learning experience.

The key is to give your users a choice over what they see, and put the power in their hands to use the documentation as much as they like. This means if they need more information on a subject they can easily find it, but aren’t overwhelmed by information.

Step in at the critical moments when users make errors, and offer them your minimalist documentation to help them succeed.

KnowledgeOwl is our very own knowledge base software. Take it for a free spin.

[1] The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill (1990) By John M. Carroll