Minimalistic documentation

Whenever I am asked for an example of good documentation, my answer is the same - the documentation that comes with your microwave. The microwave was a revolutionary gadget. Unlike the washing machine, vaccuum cleaner, grinder, or dishwasher that did the same thing you did, just faster and better; the microwave changed the way you cooked. The documentation that comes with the microwave mirrors this change. The part on how to use the device is about 20% of the manual. The rest of it is dedicated to telling you how to cook with a microwave. You can still make the same cake or the same boiled egg, but in a new way. It needed people to change behaviors and expectations. This could only be done through documentation.

Now think about the documentation that accompanies software products. A good percentage of the documentation is spent describing straight-line scenarios. Documentation for an HRMS explaining how to add an employee. The user manual of an accounting software telling you how to pull a P&L statement. The help page for a messaging tool telling you how to compose a message.

If you need documentation to help your customer use the product for the most basic task - no amount of documentation is going to save the product. Think about it, how many times did you have someone complain about having trouble with a basic function? Most of the time people are frustrated with the documentation because the corner cases have not been documented well enough. Unfortunately, writers spend a lot of time and energy documenting stuff people don't need or shouldn't need.

Here is what I propose

Only document secondary scenarios

For each feature in the product, identify the primary and secondary scenarios. The primary scenarios should require no documentation apart from a mention in the user guide. Secondary scenarios, or use cases, that require special actions, should be documented in detail.

This shift in focus ensures that the workflow of primary scenarios are done with care since the safety net of documentation no longer exists. It also frees up bandwidth for the writer to focus on helping users build and implement efficient processes using the tool and to document the more complicated tasks.

In one of my earlier roles, an Inventory report had two columns that sat next to each other titled Amount and Type. When I called out that these should actually be Quantity and Unit of Measure, I was told that the users are already used to it and hence it didn't make sense to change. A month later, I received a request to define the two terms inside the documentation because it was confusing to customers. We can document it. But does that help? Is someone looking at that report going to go into documentation to figure out what the two columns mean? When we receive customer feedback, we must look beyond the words to find the solution. The complaint here isn't that the terms are confusing to use. It's that the columns are misnamed. The solution isn't documentation.

In another case, the team received a request to add content to the documentation that a certain user-defined name can only contain alphabets (in any language), numbers, and a set of special characters only. Full credit to my writer, he asked the product manager two very pertinent questions:

• What are the blocking characters? It turns out, they were just five of them. So the writer suggested we should call those out instead of putting the load on the reader to figure out the error. You be the judge on which one makes more sense. The name can only contain alphabets (in any language), numbers, and the following special characters (` ~ ! % ^ & * ( ) , . " ' < > _ = + /) The name cannot contain # $ % - and ?

• Why are we putting this in the documentation? His suggestion was to put it on the UI. A simple solution that would lead to reduced friction and frustration.

Documentation should not be used as a bandaid for bad product design. Instead, documentation should be used as a tactical weapon used in very specific scenarios that cannot be handled by the user interface. For example, a question such as "should I use option 1 or option 2". If the decision changes the behaviour of the product or has long-term implications, it should be written about in detail.

For far too long, documentation teams when asked to jump simply ask "how high". By doing this, we are letting down the product, our users, and our practice. The first question shouldn't be "how high", it should be "why". When you have a hammer, every problem looks like a nail. In the same way, to every documentor, the solution to every problem in the product is documentation. This is the wrong approach. Think of documentation as a gun with limited ammunition. Use each round with deliberation.

When used properly, documentation adds to the usability of the product. When used indiscriminately, it is just noise.