Writing for your audience

Talk to any technical writer or product documentor about documentation processes and audience analysis comes up without fail. One look at the documentation and you can see that none of the learnings from the analysis were applied. I see a few errors crop up consistently. 

• Explaining things the user already knows. It is easy to see where this comes from. The feature is planned by a product manager, designed by a UX designer, built by a software engineer, and documented by a technical writer, none of whom belong to the world inhabited by the user/reader. What may be new or interesting information to us, is not necessarily new or interesting to the reader. It’s like describing water to a fish. I have seen documentation that describes the GST number field in a software aimed at accountants. This is noise. The cost of the three or four sentences in the documentation is felt in multiple ways. For one, the user is irritated at having to wade through information that is obvious to her. It increases translation costs. It increases maintenance overheads. 

• Explaining things the user has no control over. This usually comes from someone in the product team being extremely proud of their work and wanting to showcase it. Again, this is noise that the user has to wade through before getting to the interesting stuff. I recently came across a user manual article explaining the algorithm used to make a feature work. As I read it, I assumed that the user would need to choose one of multiple options. But that was it. There was no option to choose. This was the algorithm for the feature, the user had no agency here. So why tell them about it?

• Not explaining things that are not obvious. This comes from the assumption that the user knows that the product team knows. I was using a software that allowed a business owner to track collection information from various outlets. On the page where you can create a new outlet, there is a Transaction Series field. The instruction just tells you to select an existing series or to create a new one. But nowhere does it tell you what the field does. Here is the field description table for the form.

Field	Description
Outlet name	Name of the outlet
Manager name	Name of the manager
Opening date	Date on which the outlet was opened
GST number	GST number under which the outlet is registered
Transaction series	Transaction series to use for the outlet.

42 words of noise. Instead, all this page really required was:

Enter the required information. Transaction series is a sequence of characters that will precede the invoice number. For example, for the Gachibowli store, you might want to place GAC_ before every invoice number issued from that store - GAC_001, GAC_002, and so on.

42 words of useful information. 

First the education system, then misaligned incentives at organizations have pushed us to normalize writing more words over writing the right words. It is such a cliche that the users’ needs take priority over everything else. But until we internalize it, we are most certainly breaking a golden rule in every article we produce.