Adopting minimalism in your docs

A traditional approach to documentation is to explain everything, down to the features of the user interface. My first project as an intern trying to write good documentation is a great (by which I mean terrible) example of how messy this approach can be. But there’s more to it than that—once you start documenting everything, it becomes easy to lose sight of what the user needs, what the user wants to do, and what task the user is having trouble completing.

Over-explaining concepts and instructions is a trap you can easily fall into. Developers and engineers sometimes pressure us technical writers to make sure the user has an explanation for absolutely everything. On its face, having more information sounds better, right?

Not necessarily. MyHowTo.Org explains the issue succinctly:

The expression "the more the better" does not apply to the documentation. At least after a certain threshold. If there is too much documentation for everyone, the people do not read it. If the people do not read it, first of all it is a waste of time to write and maintain this documentation. Secondly, it does not serve its purpose. The more documentation you have, the more difficult is to maintain it (and the dependency is not linear!). And the outdated documentation that has lost its connections with the real system may be worse than the lack of the documentation.

The solution

How do you avoid the trap of explaining too much? Good question.

Minimalism can help. JoAnn Hackos, a leader in the world of documentation, outlines how you can apply minimalism in your documentation:

• Principle 1: Choose an action-oriented approach.
• Principle 2: Anchor the tool in the task domain.
• Principle 3: Support error recognition and recovery.
• Principle 4: Support reading to do, study, and locate.

In short, eliminate extraneous information. Focusing on user needs is a great way to get started. If you can outline the action the user is trying to take, or the specific concept the user needs before they can proceed, you whittle down all the information you know about your product down to a single topic. From there, you can approach the topic to ensure the user can complete their task, and identify the potential obstacles they may need to work around or mitigate.

Putting minimalism into practice

At Red Hat, we periodically crowdsource our editing using minimalism as a guide. A writer submits a topic in draft state, and other writers and editors gather with a modified template of Hackos’s approach:

• Focus on the reader's goals; take an action-oriented approach.
• Eliminate fluff, long Introductions, and unnecessary context.
• Focus on findability: the best possible location.
• Use clear titles.
• Include troubleshooting, error recovery, and verification steps.

In April, I asked my fellow writers and editors to review a draft of an overview doc I was writing on how Red Hat uses the Candlepin and Pulp engines in Red Hat Subscription Management. This doc was technically difficult for me, and I was struggling with how to best outline the information. Specifically, because it was a new topic for me, I was afraid I would add too much detail in the process of ensuring that I personally understood it, which is not helpful for the user. Here's feedback I received:

Image by:

^{Feedback from Red Hat writers and editors on overview documentation draft}

Crowdsourcing minimalism helped me achieve that goal by telling me what I needed to eliminate, where I over-explained information, and where I needed to add more information. Even though I was independently interested in keeping my docs clean and structured, I still needed more help making that happen than a standard edit/review of a doc could have provided.

Want to learn more?

Here is Ingrid Towey's presentation on utilizing minimalism in documentation, from this year's Write the Docs conference in Portland, Oregon.