Technical writers are almost always taught to overexplain the concepts and tasks they’re documenting to ensure that users never feel frustrated or confused.
But what if that isn’t always the best approach to documentation? What if users don’t want to read pages upon pages of product guides to be able to interact with your software?
In this article, we’re going to present you with an alternative approach to technical writing: minimalism.
Let’s find out what can happen when technical documentation lightly supports users and doesn’t interfere with their process of learning to operate a software product.
What Is Minimalism in Technical Writing
The principle behind creating technical documentation is quite simple.
Since newcomers have no experience handling a particular tech product, they need to consult technical documentation in order to learn how to use it successfully.
The classical approach to documentation takes this principle very literally.
Within this approach, every concept is overexplained, and every action is described in micro-steps to ensure the user is never confused or unsure of what they need to do next.
All of this may seem very logical, but research has shown that this classic approach to documentation doesn’t really reflect the behavior of real-life technology users.
Observing how people interact with computer systems, John M. Carroll, the renowned information scientist, noticed a peculiar pattern.
His research showed that the less knowledge and experience people had when interacting with a system, the less they would consult the documentation.
Carroll goes on to explain that people instinctively want to learn how to use a product using the experience and knowledge they already have.
However, this existing mental model can come into conflict with the written instructions, which causes the mind to reject the instructions and trust its own experience.
He calls this phenomenon the paradox of sense-making:
“People are situated in a world more real to them than a series of steps, a world that provides rich context and convention for everything they do. People are always already trying things out, thinking things through, trying to relate what they already know to what is going on, recovering from errors. In a word, they are too busy learning to make much use of the instructions. This is the paradox of sense-making.”
Carroll’s solution to this problem was to strip away all unnecessary information from documentation, make it action-focused rather than descriptive, and use simple language to explain how the product works.
The idea behind this new approach was to support users coming into contact with computer systems rather than interfering in their learning process by making them wade through endless guides, manuals, and explanations.
And thus, the minimalist approach to creating documentation was born—and soon adopted by tech giants like IBM, Microsoft, HP, and Cisco.
The minimalist approach to creating documentation is still the method of choice of many technical writers in contemporary software and other types of technical documentation.
The following sections will explain why minimalism persists in documentation and how you can make your own technical writing more minimalist to serve your users better.
Why Should You Use Minimalist Principles
To reiterate a previous point, when readers are confronted with too much documentation, they tend to abandon it and simply try to figure out the product on their own.
This is problematic for two main reasons:
- Your documentation is now useless to the user, meaning you’ve wasted resources creating it.
- The user is in danger of picking up the wrong way of using your product, meaning they might not get any value from it.
It, therefore, follows that the biggest benefit of taking a minimalistic approach to documentation is a better allocation of resources.
Think about it. Creating a large amount of documentation costs a lot of money. In fact, in the tech industry, documentation is valued at up to 10% of the entire product design cost.
This figure factors in the resources and tasks that go into creating, distributing, and maintaining a large volume of documentation in your knowledge base.
But with a minimalist approach, this cost can be significantly reduced without sacrificing the positive experience your users have as they begin their journey with your product.
Quite the contrary, users won’t have to waste time sifting through flowery language and lengthy descriptions to find the information they need and can spend more time interacting with the product, which will increase their engagement level with it.
Minimalism is also very much in line with the Agile approach to software development, the contemporary method used by software companies all over the world.
Within the Agile approach, documentation is created later in the development process (just in time or JIT documentation).
As a result, it's necessarily produced without too much detail as there simply isn’t enough time to create comprehensive documents with all the bells and whistles.
Instead, Agile and minimal documentation contains only what the user needs to work with the product and nothing else.
Therefore, by keeping documentation minimalistic, you’re aligning your efforts with the process of software development and making it easy for your team to pivot, make changes, and adapt the documentation as the product itself changes during production.
All in all, minimal documentation is less resource-intensive and easier for the user to digest, but it doesn’t damage the user experience or product adoption.
It’s also beneficial for the technical writing team because it aligns their work with that of the development team and enables them to be more adaptive and reactive with the documentation process.
This allows technical writers to follow the software development process more closely and effectively.
How to Achieve Minimalism in Technical Writing
Now that we’ve established that minimalism in technical writing is a safe and productive approach to documentation that won’t in any way hurt your team or the end-users, let’s go over some minimalist principles.
These principles double as actionable tips you can easily apply to slim down your documentation while also making it more effective and impactful.
Make Tasks in Your Documentation Action-Focused
A lot of documentation emphasizes the concept of “knowing” over the concept of “doing.”
With this approach, you’re describing the nature, characteristics, and features of your product to make the user aware of everything they can accomplish with your product.
Take a look at this article about channels from Slack, for example:
The article provides the basic definitions and establishes what can be done with this feature of the communication app.
This is a great resource, but it doesn’t actually tell the user how to accomplish something or what steps need to be taken to complete a task such as creating a channel.
In other words, it’s not action-oriented, meaning users can make do without it.
Now let’s examine another document from the same source. This one is about adding people to a Slack message.
Notice how concise and actionable this document is. It presents the user with a clear way forward when they need to complete a task using the software.
If a user doesn’t know how to complete this particular task, this is a document they won’t be able to continue their work without.
So as you can see, there are types of documents your users can live without.
Others, the ones that show them how to do something, rather than describing the capabilities of the software, are the ones that are absolutely necessary to them.
For a minimalist approach to documentation, focus on the latter kind of action-focused documentation.
Make Some Parts of the Content Reusable
A particular case where minimal documentation becomes a very useful approach is in larger companies that are working on several products at the same time or on a single project with a great number of features.
The minimalist method in those situations entails making parts of the documentation reusable so that they can be applied easily to multiple projects without changes having to be made to the document.
So, how can you make your content reusable?
The easiest way is to strip it clean of all specific information, such as the name and/or version of the product.
By doing that, you’ll have a collection of generic documentation you can reuse and adapt to your needs.
Here’s an example of reusable documentation from IBM (as you’ll remember, IBM was one of the first adopters of minimalist documentation):
This is the installation guide for IBM’s Operational Decision Manager. As you can see, the information architecture for this action is as generic as it can be.
It follows a standard for all installation guides (components, preliminary steps, different installation options).
The product is never mentioned by name and is simply referred to as “product.”
Building an archive of reusable content may seem like a daunting task all on its own, but if you’re using quality documentation software, it’s actually quite easy to do.
For example, Archbee has a reusable content feature that will enable you to create content snippets, save them, and then easily paste them into your documentation.
Source: Archbee on YouTube
For a company as big as IBM, making content reusable cuts down significantly on the amount of documentation that needs to be produced.
Articles follow a similar outline and generic names are given wherever possible so that minimal specific information needs to be added in for the document to work.
Use Standardized Language
Another hallmark of minimalist documentation is standardized language.
This principle is all about reducing the number of terms you’re using to the lowest possible volume to add consistency to your documents and avoid confusion on the part of the user.
And here’s why.
Building and using software comes with its own vocabulary and vernacular that doesn't always come naturally to the end-users of your product, even if they have developer knowledge.
Therefore, it’s a good idea not to confuse users by using a wide vocabulary for similar concepts.
A much smarter practice is to decide upfront on the expressions, terms, and phrases for the common concepts that are going to appear in your documentation and then stick to them.
One tool that could help you do this is a house style and glossary of terms that’s going to set the ground rules for how you express yourself in all technical documents.
Building such a resource would take an enormous amount of time (which is not very minimalist), so feel free to borrow one of the technical documentation glossaries that already exist.
We recommend Google’s Word List because it’s very comprehensive and reflects the way people actually talk, which will make your documentation sound more natural.
Remember, the minimalist approach to anything always attempts to remove redundancies and make things as basic and simple as possible. This can be applied to language as well.
If you want to uncomplicate your documentation, do your best to standardize your language and don’t use multiple terms to mean the same thing.
Avoid Using Jargon
To build on our previous point, another way to simplify the language in your documentation is to try to minimize the use of jargon as much as possible.
In the last subsection, we talked about using just one term for a single concept.
This automatically excludes all types of jargon because jargon is essentially a lesser-known or less formal term for something.
Here are some examples of political jargon. Do you know all of these alternative terms for “recession?”
In addition to that, technical writers often make the mistake of perceiving a concept as very familiar to audiences when it actually isn’t.
In those cases, writers feel comfortable using industry-specific jargon that users might not understand.
Therefore, to avoid any confusion and keep the complexity of your documentation as low as possible, the best course of action is to only use widely-known terms that are likely to be understood by the largest possible audience.
This rule of thumb is supported by almost every technical writing style guide in existence.
For example, the Microsoft Style Guide recommends not using jargon in any situation where another, more familiar term could be used.
In short, minimalism and jargon just don’t mix. Jargon can obscure the meaning of a concept, and if there’s a more widely-used term for that concept, there’s simply no reason to use it.
When Should You Avoid Minimalism in Technical Writing
In this article, we’ve established that a minimalist approach to documentation can help you simultaneously reduce the resources needed to create, distribute, and maintain documentation and increase the quality of your users’ interactions with the product.
So, does that mean that minimalism is always the way to go?
Not so fast.
There are many types of technical documentation, particularly in the software industry, and not all of them are effective when they’re stripped to the bare essentials.
This is especially true for more advanced types of documentation that explain very complex notions and actions.
In such cases, users are more likely to misunderstand instructions or get confused along the way, so overexplaining the most complicated parts isn’t such a bad idea.
API documentation is a good case in point. API documentation is created for a developer audience, and it has the tough job of explaining how a product’s Application Programming Interface (API) can be integrated with other software.
Along with textual descriptions and step-by-step instructions, this type of documentation most often has extra layers of explanation, such as code examples, use cases, error lists, and other resources to ensure that developers understand the documentation and can apply the knowledge without any problems.
For example, GitHub’s API documentation supplements textual explanations with code examples so that users can instantly try out what they’ve learned.
These additional resources aren’t just nice to have. They’re essential to the developer’s learning process and can make the difference between good and bad API documentation.
Developers themselves will tell you that there’s no such thing as too many examples and resources when it comes to APIs.
Therefore, while user guides and simple tutorials work best when they’re laser-focused and cleansed from any superfluous information, more advanced documentation can’t always be improved with a minimalist approach.
So if you’re documenting complex procedures or showing users how to complete sensitive tasks that need a bit more skill, make sure you give them all the information they need.
Minimalism is definitely a useful approach, but it’s not a universal rule, so use your best judgment.
Conclusion
The purpose of this article was to show you that less really can be more in technical writing. A minimalist approach to documentation can seriously cut down on your workload as a technical writer and save your company’s resources.
At the same time, it can work wonders to improve user experience and boost the engagement levels of your customers when they approach your software.
Providing users with fewer resources may seem scary at first, but we encourage you to try out the tips we provided in this article and see how your audience responds.
You should start seeing some impressive results very quickly.
