Image by Shimelle Laine on Flickr.com | Creative Commons
Nobody reads the documentation. We’ve all heard it. We have all had our work dismissed with this simple half-truth. How should we respond?
If it were simply not true, the response would be easy enough. We could simply show that it is read, and that would be that.
The problem is, people really don’t read the documentation. That is, they do not sit down in a comfortable chair with a cup of coffee and set out to read manuals from cover to cover. As John Carroll discovered, in his research that led to The Nurnberg Funnel, even people who think that is what they do, who will tell you that is what they do, don’t actually do it.
People read novels. They don’t read documentation.
Documentation is hardly alone this problem. People don’t read recipe books or phone books or encyclopedias or dictionaries or tide tables. Increasingly, they don’t read newspapers or magazines.
They don’t read these things, but that does not mean they don’t use them. They don’t read them, but they do consult them. They use them tactically to retrieve individual pieces of information as and when they need them.
There is a big difference between consulting an information source and reading it. Reading can take hours or days. Consulting takes minutes or seconds. Reading requires time set aside for the activity of reading. Consulting takes place in the context of another activity.
If a person is keeping a mental time sheet (or a physical one), it is unlikely that they will distinguish the time spent consulting information as “reading time.” Sitting down to read a book would be recorded separately as reading time. Looking up information in the course of your work will likely be recorded as part and parcel of task time.
This distinction is highly important to the question of whether documentation gets read. For some tasks, a number of references to information may be required, and between the time spent to find the information and the time spent reading it, the worker might spend a significant portion of their day on consulting content without registering a second of it as “reading” time.
So, our response to “no one reads the documentation” should be “Absolutely. People don’t read documentation. They consult it.”
How effective people are at consulting content can have a big impact on their productivity. Every time they pause to consult documentation, there is a pause in their productivity. Every time they struggle to find the information that they are looking for, there is a longer pause in their productivity. Every time they fail to find the information that they are looking for and give up on the task, or invent their own way to get it done, there is a big pause in their productivity, and likely a significant permanent slowdown in their productivity even when they do get back to work.
Ask them, at the end of their day, “Did you read the documentation?” and most people will probably say no. They did not take time out to read. They were too busy getting work done. Show them the aggregate information seeking and consuming time from their day, though, and they will probably be surprised at just how much of their day was actually spent with content. Reading time might not register on their time sheets, or even in their recollections, but information-seeking time and effectiveness can make a huge difference to the effectiveness of their job performance.
This is not to say that people never complain about information being hard to find. They do complain about it, sometimes quite loudly and bitterly. But we should not mistake this complaining for proof that people read documentation. What people commonly complain about, by and large, is that when they go to reference a particular piece of information, they can’t find it, or they can’t understand it if they do find it.
Yes, people consult documentation. No, they don’t read it. The fact that they consult it is more than sufficient justification for creating it, and more than sufficient justification for doing it well. That is all the answer we need to the charge that people do not read documentation.
Except for one thing: we keep designing and organizing information to be read rather than to be consulted. If we are going to make an effective reply to those who say that no one reads the documentation, then there are a few things we need to face up to.
Designing to be Consulted, not Read
First and foremost, if we are going to argue that content is consulted, even if it isn’t read, we have to stop designing, writing, and organizing it as if it were going to be read, and start designing, writing, and organizing it to be consulted.
A large part of Every Page is Page One is about designing to be consulted. There are two senses to this. One is designing the topic to be consulted as a whole—for the reader to read this one topic rather than reading a whole manual or documentation set, but to read the whole topic. This is why an Every Page is Page One topic should be self-contained, have a specific and limited purpose, and establish its context.
The second senseis designing the topic to be consulted in pieces. Design it for the reader who will not read the whole topic but who will consult pieces of it. This is why an Every Page is Page One topic should follow a consistent (and explicit) topic type, and why it should stay on one level and assume that the reader is qualified—so that the information the reader needs can be found in a consistent place and in a consistent form within the topic.
Rich linking supports consulting a topic in both senses. It helps the reader who wants to consult either a whole topic or part of one get from an imperfect search result to the topic that they really need,.It helps the reader with an imperfect background fill in the gaps in their knowledge without having to read an entire manual.
Designing for Search, not TOC
Next, we need to face up to the fact that for most people, the primary method they use for finding content is not your table of contents or your index, or any other navigation tools you provide: it is search.
Complain all you like about the imperfections and ambiguities of search results. The fact is that search is easy to do and the results are good enough most of the time. It is the information finding method of choice for more and more people.
Yes, it is true that some people search badly and don’t find information even when it exists. But that is true for all other forms of information finding as well. In fact, in many cases search is demonstrably better at surfacing information than other methods. In some cases, it is demonstrably worse. But most people can’t anticipate when search will be better or worse, and most cannot tell the difference between a search finding nothing and there being nothing to find. The net result is: most people search most of the time.
Rather than expending effort on elaborate top-down organization and navigation systems that few people use, we should be focusing more of our effort on designing content to be found by search engines, and to be useful to reader once they find it.
We should also be making effective use of linking to help readers who have not quite arrived at the right place to go the last mile to get to the content that they really need. Use links to enable local navigation within the subject affinities of the current topic.
Designing for Web, not Help Systems
Third, we have to face up to the fact that when people search for information, the first place they go is the web. And when they do a search on the web, it is not because they are looking for our documentation with the intent to use it exclusively. They are looking for information from a variety of sources. Or, more to the point, they are looking for information without thinking much about the source it comes from. They want content from a broad set of perspectives, and often trust and value the content produced by fellow users over content provided by the vendor.
The search that the reader uses to find information that your content contains (they are not looking for your content!) is going to include results from many different sources. Our first challenge is to be one of those sources—to do the things that lead to our content ranking high with search engines. And if you imagine that that is simply a matter of some SEO tricks, you have missed the news about how much quality and relevance of content matters to search ranking today.
And you can’t expect to get good search ranking for a section of a book presented as a separate page within a traditionally framed online help system. Even if the search engine can see that content (and that is not always the case), it can have a hard time assessing the content and its relevance, since it is often not stated as part of the page content, but was established on previous pages, which the search engine cannot see or associate with the current page. (Readers can have the same issue when they do find such a page.)
And even if we do get search engine ranking, we still need the reader to recognize our content as the information they need. Merely being found is not enough when the reader has so many resources to choose from. If it is not immediately clear what our content provides, it is likely to be overlooked, even if it is ranked in the top five search results.
In other words, we can no long act, think, design, or write as if we own the audience, as if they have no choice except to come to us for information. Now, our challenge now is to stand out from the crowd—to be the better source of information, the one that is easier to find, easier to understand, and easier to act upon effectively.
Designing for Colloquium, not Lecture
And on that note, we also have to face up to the fact that technical communication is no longer a lecture, no longer one party dictating and the other party simply listening. Technical communication is now a conversation in which many different parties participate actively, and in which information comes from many different perspectives representing many different interests and points of view.
Actually, this idea is not new. This conversation is always how technical communication has worked in the larger world. It is just that our particular enclave—technical publications—has traditionally stood outside of this technical colloquium in which the rest of the world has always engaged. Our old role used to be to deposit documentation into the colloquium and walk away, without ever listening to it or taking any notice of what was being said. (Indeed, we would sometimes attempt to warn our readers against listening to anything outside of what the official manuals said, or of participating in the colloquium in any way.)
This approach simply won’t fly anymore. In an age in which people consult information rather than reading it, they also consult each other, and they form the bonds of respect and trust within the context of that conversation. Trust cannot be bought with a gilded spine any more. It is won and lost in the honest, direct, and personal exchanges in the colloquium of technical communications.
This change doesn’t mean that there is no place for written documentation within the colloquium. A colloquium is more than just a conversation. A colloquium places a value on preserving, refining, and publishing what is of lasting value. But it is no longer enough to dump content into the colloquium from without. We have to be part of it.
People do not read documentation. They do consult many forms of source of content and expertise to get their work done. Technical communications can and should be one of the sources of both content and expertise that they consult, and an instrument for building up their attachment to and trust in the company that creates the tools they use. The new colloquium and the new trust economy that the web has created provide a great opportunity than ever form technical communications to make a difference to the fortunes of a vendor. But change comes only if we face these truths about the state of the marketplace and change what we do accordingly.
