Write for people who actually read documentation

By | 2013/02/25

One of the biggest mistakes we make in technical communication is trying to write for every user.

Sacrilege, I know, but hear me out. Many users don’t read documentation. They don’t not read documentation because the documentation is bad, or not written for their level, or uses big words. The don’t read documentation because they are the kind of people who don’t read documentation. It is a fixed part of their character and their outlook on life, and nothing you can do with the documentation will change it.

Users who won't read docs are like kids who won't eat new food. They just won't.  Image courtesy of federico stevanin / FreeDigitalPhotos.net

Users who won’t read docs are like kids who won’t eat new food. They just won’t. Image courtesy of federico stevanin / FreeDigitalPhotos.net

It’s like a child who won’t eat anything new. It isn’t because they have tried the new food and not liked it. It is because they don’t like new food. Even if forced to ingest it, they will not like it, no matter what it tastes like, because they are the sort of child who does not like new food.

Of course, you can’t force the user who doesn’t read documentation to read it anyway, but even if you could, they would not like it because they are not the sort of person who reads documentation.

I know what you’re thinking. If they won’t read documentation, they will watch videos, so we should move all of our docs to video. But no, while there may be some people who prefer to get their instruction from a video rather than text, people who won’t read instructions are primarily people who don’t want to be instructed. The medium is not the sticking point, it is the instruction, the unpleasant exercise of expending mental energy required to learn something of slight or passing interest, and especially of learning it not from a person, or from experience but from some impersonal and abstract lump of content. They just don’t like it.

There may be many causes of this refusal to be instructed. Some may be genetically indisposed, some scared by early childhood trauma, some trained by the schools to regard any form of learning as drudgery followed by humiliation. Some people expect and demand that if they pay for something it should just work without need for directions. Some feel they don’t have time to read, some that they don’t have the mental energy or the room in their brain for new information. And some, who are willing or even keen to be instructed, have nevertheless been so disappointed so many times by the bad documentation that accompanies so many products that they will never read any documentation any more, but will seek instruction elsewhere.

There are many writers who see this host of non-documentation reading folks as a challenge. If only we can make the docs good enough, or sexy enough, or graphical enough, or entirely video, they believe, they can turn these non-documentation reading folk into documentation reading, and even documentation loving folk.

This is a highly dubious proposition, since all you can do is put docs in front of them, and they are people who don’t read documentation. And as a business proposition, it makes no sense at all. The marginal utility of converting one or two non-documentation-reading folk, in terms of its contribution to improving share or margins, or reducing costs, is zero. If that kind of heroic turnaround of people’s basic orientation to knowledge is what lights your fire, you should go work in an inner city school or some similar environment that calls for heroic teaching. It is not what technical communication, as a business process, is about.

To be sure, there are some people who have no choice but to read the documentation. If you work in a regulated profession with significant safety or security concerns, you will probably be required to read the documentation, and pass a test on it, before you are allowed to play with the toys.

The interesting question here is, how many non-documentation-reading people choose to go into professions where documentation reading is a job requirement? Probably not a lot. Those who do will clearly be highly motivated by some other aspect of the profession they want to enter. They will reshape themselves to meet the requirements of their chosen occupation. They may not have been born documentation-readers, but they will teach themselves to become documentation readers, at least within the scope of their profession. As an audience, therefore, they are documentation readers.

I don’t for a minute want to suggest that all documentation-reading people are highly educated, or that all non-documentation-reading people are poorly educated or unintelligent. I know lots of non-documentation-reading people who are highly intelligent and highly educated. They just don’t read documentation. And I think there are very clearly people of lower educational attainment who are documentation readers. It’s not about education or intelligence, it is about a basic orientation towards or away from documentation reading.

It is also certainly true that there are people who are documentation readers in some aspects of their life and not in others. Some may be documentation readers at work but refuse to read documentation at home. Some might be willing to read documentation for software but not for hardware. Some might be willing to read documentation in their own field but not in other fields.

But none of this matters to the prospects of them reading your documentation. Either they are the sort of people who read documentation in your domain, or they are the sort who don’t, and there is nothing you can do about it.

The real audience for your documentation  therefore, is not the set of all users, but the set of people who are the kind of people who read documentation. Everyone else will get their information some other way, or do without it. There is no point in your trying to cater to them. They are never going to look at your stuff. Your efforts will produce zero net gain to your company, and zero net gain to its customers.

Non-documentation-reading people may receive your information at second hand, from someone they know who is a documentation reader, or they may just figure it out by trial and error, but they will never read the documentation for themselves.

The real audience for your documentation, however, is not a strict subset of the users of your product. Other people, such as analysts, journalists, bloggers, and prospective customers may read your documentation even though they don’t use the product.

The audience for your documentation, then, is simply the set of people who are interested in reading your documentation. This is good news, because they are a relatively homogeneous group, and relatively easy to write for.  The only danger is that you may turn them off with all the gegaws and antics you have stuffed into your docs in a vain attempt to reach the non-documentation-reading part of your user base.

Stop trying to cater to every user, therefore, and design your documentation for the people who actually read documentation. Your life will be a lot easier, and you will produce more value for your company, and for its customers.

17 thoughts on “Write for people who actually read documentation

  1. Vinish Garg


    A very valid point to identify that core subset of users who may actually be interested to read the documentation. But how do we do that? If I have a CRM system to document, I would assume that it may be used by businesses of different scales and size across the geographies.

    And my objective is to cater to requirements of all users who may be using that CRM. While identifying the core subset of users who I expect to read the documentation, I cannot afford to leave even 1% users who ‘may’ refer to the documentation. Isn’t it that the objective of documentation is to cater to requirements of ALL possible user (sets and subsets and super sets)? Else, it is nearly impossible to identify that core subset of users accurately.

    1. Mark Baker Post author

      Thanks for the comment Vinish.

      Actually, I would argue that the purpose of the documentation is to improve margins, improve market share, and reduce costs. Attempting not to leave even 1% of the users out probably isn’t the best way to do that.

      The Bible says that the shepherd cares more for the 1 sheep who is lost than for the 99 who are not lost. That is good morality, but poor economics. The marginal cost of the 1% of sheep who are lost is much greater than the marginal cost of the 99%.

      Technical documentation is a component of a product, and all products are targeted to a segment of the market. You don’t try to sell the same product to everyone. You identify a key demographics that you can market and sell to economically and you focus on them, because that is where the money is.

      There will always be potential customers around the margins of the target demographic who you might get if you invested more in development. But if it costs more in development than the number of additional customers you gain, then you are losing money going after the 1% of lost sheep.

      It is important to remember that documentation is a commercial product, not a moral obligation. It should be judged by commercial criteria, not moral imperatives.

      1. Vinish Garg

        Excellently clarified. I loved your clarity of thought process to explain it to me. Agreed whole heartedly.

  2. Scott Hatcher

    I’d like to share this with several product teams I’ve worked with over the years (but of course, they wouldn’t read it). Thanks for reinforcing the need to focus on the true audience, and to give them what they really need, without unnecessary bells and whistles.

    1. Mark Baker Post author

      Thanks for the comment, Scott.

      “but of course, they wouldn’t read it” — LOL! Too true.

  3. Alex Knappe

    In my comment to your last post, I spoke about a perfect tech comm world. Now you are doing the same.
    While you point out many valid points, you’re creating another perfect world scenario.
    There are many influences from the outside, that hinder us to do what you ask for.
    For one thing, there are quite restrictive laws concerning documentation. They tell us (freely translated) to write documentation, that even a trained monkey could understand.
    On the other hand, writing “only for the people, that actually read the docs” would require an indepth target group analysis. Common sense in tech comm is, that a target group analysis should be done before you even write the first line. Fact is, nobody does that. In fall last year, the topic was discussed on a convention I attended. One question on the agenda was, how many tech writers actually do target group analysis in practice. Well, from about 150 tech writers in the room, only one raised her hand – and she still was an university student.
    So, as long as out target group analysis (we all do that in some way or the other) consists of wild or educated guessing, we will not know who we are writing for.

    1. Mark Baker Post author

      Well, if your documentation content is mandated by Law, there is nothing much you can do about it. Unless documentation reading is also mandated by law, however, there will be no economic value in producing the mandated docs, and we can expect that it will be done pro-forma at minimal cost. I have no advice for doing that.

      Yes, conventional tech comm doctrine calls for a user needs analysis (I assume that is the North American term for what you call target group analysis). And yes, it seldom gets done, because it is too hard and it costs too much.

      What I have always done, and insisted writers working for me do, is to prepare a Theory of the User and Theory of Use document to describe the audience they are going to write for. I then circulate that document for review to every customer facing function I can cajole into responding, and incorporate their feedback into the document.

      This is considerably cheaper than a user needs analysis study, and considerably better than each writer guessing at the audience for each thing they write.

      However we decide who our users are, however, we can still make a division, between those who will read the docs and those who won’t. It won’t be perfect, but perfect or not, writing for people who don’t read the docs is still pointless.

    1. Mark Baker Post author

      Thanks Marcia.

      They say the boy is father to the man, and so the fussy eater is father to the fussy reader.

  4. K.Vee.Shanker.

    Hi Mark,

    I fully agree with your view that most of the users do not read docs. Well, that is only part of the picture.
    And you’ve lamented (more than once!) about the poor documentation you see everywhere. But, I wonder whether you recognize the importance(?) given by the Delivery Head/Product Manager to the documentation during the entire product development to the final release? Who’s responsible for the poor quality? Frustrated Writers/Editors alone?
    The less said about it, the better!

    1. Mark Baker Post author

      Hi K.Vee,

      I don’t know if it most of the users. I suspect that the proportions are different for every product and for every demographic. I just know that there are some users who don’t read manuals and that there is no point writing for them.

      The prevalence of poor documentation probably goes a long way to explain why some users have abandoned reading manuals. How much is the product manager to blame? I’m not sure. But there is certainly a lot that writers could do to improve the quality of documentation, even without support from the PM. Moving away from designing information for paper would be a good start.

      1. Alex Knappe

        That paper thing: If you are selling stuff in Europe, you are forced to have a fully blown paper documentation. I guess no one bothers if software has none – but as soon as you’re selling any hardware, customs offices will intervene.

        1. Mark Baker Post author

          There is a difference between designing for paper and supplying paper. For decades we have designed for paper and delivered to the Web — with results that are little short of disastrous.

          The Web is not the primary means by which people seek technical information, and we should be designing for the Web. If we also need to produce paper, we should produce paper from the material designed for the Web.

          Creating paper docs from material designed for the Web produces a much better result than creating Web content from material designed for paper. Creating a linear presentation of non-linear material is easy enough. Creating a non-linear presentation of linear material is really tough.

          I don’t advocate for the abandonment to paper. It still has a role. What I advocate for is the primacy of the Web as the design target for most technical information.

    2. Alex Knappe

      I’d like to give you a simple answer for that one: Every single person involved in the process.
      With the opinion on tech documentation it is the same as with a**holes – everyone’s got one.
      And usually (but not in every company) completely inexperienced people “create” a document through your hands, that is (sometimes) utterly useless.
      Those inexperienced people range from product managers, to legal authorities (in- and outside the company), to customers, to CEOs and even bean counters.
      As a tech writer it’s your job to get out a halfway useful result to the customers. Some do better in that, some don’t – and you can’t blame those who don’t.
      In tech comm you are Don Quichote fighting against all those pesky windmills, but you’ll never win completely.
      What Mark tries to do here (at least that is my interpretation) is to tear down at least some of those windmills standing in our way.
      I like that, even if I don’t agree with Marks conclusions very often – but he is able to point out the core problems precisely and has a very inspiring point of view on things that bother us all.

  5. Manoj Joshi

    Hello Mark,

    Thanks for giving a new direction to my thinking process while creating a documents.


Leave a Reply