Topics are About User Assistance

Many discussions of the advantages or disadvantages of topic-based documentation seem to neglect the different view of the user that is inherent in the move from the traditional textbook style manual to standalone topics. Topics are not simply a new mechanism for composing and constructing documents, nor are they simply about enabling reuse, or about adapting to the web, thought the capabilities that the web offers are tremendously important to the real change that is going on.

What topics are really about is a new model of how users use documentation. Specifically, it is a move away from the educational model of documentation in which the manual was conceived of as a textbook, to a user assistance model in which the documentation is conceived of a an immediate aid to a user in the middle of a task.

Of course, there has been a user assistance component to documentation for a long time, and good user assistance has always been topic based. But in the organizations that took user assistance seriously (as opposed to just chopping up a textbook and calling it help, which too many organizations still do) user assistance tended to be considered as something separate from the core documentation, which was still written in traditional textbook form.

A move to topic-based documentation is, in effect, a move to a documentation set that is structured entirely as user assistance. It is the abandonment of the textbook model, and of the presumptions about the user’s needs and habits that are inherent in that model.

One of the most frequent questions about topic-based writing is how to handle tutorials. The problem is that a tutorial is based on a very different assumption about user needs and behavior than a user assistance topic.  It assumes that the user wants to be taught.

Being taught and learning are very different things.  When you consent to be taught, you set aside a period of time, apart from your regular work. You put yourself in the hands of teacher and submit yourself to the curriculum of that teacher, hoping that in so doing you will accelerate your overall learning. But you also know and accept that some of the time you are going to be taught things you already know, that some of the time you are going to be taught things you are not interested in, that you are probably not going to be taught all the things you do want to know, and that poor teaching or lack of attention on your own part can mean that you learn nothing at all from being taught.

For these and other reasons, many users do not have the patience for being taught. As the minimalism studies demonstrated, adult learners generally prefer to learn by doing. Other users are not interested in either learning or being taught. They simply want to complete a task without having their mental furniture disturbed in the least.

The Venn diagram above covers the possibilities. You can do without leaning, learn without doing, be taught without leaning, learn without being taught, learn by doing, be taught by doing (exercises), and you can learn from the exercises you do while being taught (the center of the diagram).

Learning, doing, and being taught require different forms of support. If the reader want to be taught, they want a text book, a tutorial, or a training course. If they just want to do, without learning anything, they want step by step instructions and nothing else. If they want to learn by doing, they want help topics that they can refer to when they get stuck in the task they are trying to do.

Online information supported by sophisticated findability aids make it much easier for someone in learn-by-doing mode to find the information they need. This alone can change people’s preferences. People who in the past might have elected to be taught because of the difficulties of finding information ad hoc while doing, may now elect to learn by doing because they can get ad hoc information quickly and easily, not just from individual books, but from the entire Internet.

Conversely, in the book era, it was not obvious how to organize information and make it findable for user assistance purposes. The usual approach was to organize on textbook principles, and then supply an index as a secondary mechanism for random access. But, as we know, all too often the user refused to RTFM.

This is where we are in the move to topics, therefore. We are moving from the textbook model to the user assistance model as the dominant model of documentation.

Of course, this does not mean that there is no longer any demand for being taught. Training courses and tutorials are still an important element of an overall information delivery strategy. But what it does mean is that we have to start thinking in user assistance terms when we approach the main documentations, and that we need to recognize the essential relationship between topic-based design and the user assistance paradigm.

If we try to write topics while still trying to construct a textbook, we will be frustrated because the two techniques are fundamentally at odds with one another. Many of the criticisms of topic based writing amount to a complaint that the method is not suited to constructing textbooks. The criticism is right on the point in one sense — topic based writing is indeed not an easy way to construct a textbook-style document. But it also misses the point, which is that topic based writing is precisely about moving away from text books and towards a user assistance model of documentation.

Author: Mark Baker

Mark Baker is a content strategist and content engineer who helps organizations produce content that matches the way people seek and consume information on the Web today. He is the author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web. He blogs at His website is

One thought on “Topics are About User Assistance”

  1. Actually, the problem is not only in topic-based documentation and learning, but in possibility of convergence of data, user interface, documentation, and even customer requirements in natural language. Today, borders between each layer are distinct, partly, because of separation of layers, partly, because usually different people and teams are responsible of them. But is it normal? Separation of layers resolves many problems of development but at the same time creates a lot of problems for maintenance and user experience (though even for development, when a model becomes unsynchronized with requirements and expectations).

    User assistance should not be restricted with documentation only. For example, realize the problem occurs in some part of application. Today, an user should at first, synchronize the issue occurrence with documentation, that is, documentation description of the application/UI location should coincide with what an user sees. If nothing found, an user describes this location in own words and asks the tech support on that, etc. Ideally, when an user meets an error, assistance should occur in-place, that is, an application error should be identified enough to be related with appropriate documentation, online or offline help (by tech support). This information will be enough even to create history of an user experience (not sending dumps), or even direct requests for an enhancement. You may imagine it as if, an application behavior is represented somehow at a sort of app-blog and an user may comment it (but not the entire text but even parts of a text).

    In this case, doing, learning, and be taught are parts of the whole. They are different, yes. But don’t blame users for not readiness to be taught or learn. If you use an application (or some function) often, you will learn things volens-nolens, if you use it rarely, is there a sense to learn it?

Leave a Reply

Your email address will not be published. Required fields are marked *