Recently, I suggested that the move to topic based documentation should be understood as a move away from the textbook model of documentation towards a user assistance model. This move reflects a change in priorities, putting more emphasis on readers who want to learn and less on those who want to be taught.
But can we justify this change in priorities? Can we be confident that the majority of our readers actually do prefer to learn by doing rather than by being taught. If we believe John Carroll’s minimalism studies, we certainly should incline in that direction, but we also have to recognize that sometimes some readers will still want to be taught, rather than learn by doing. The question is, can we make reasonable assumptions about what proportion of our particular user community falls into each camp?
I think the answer is actually pretty simple. I think it comes down to confidence. I think confident users want to get on with the job and learn by doing. I think non-confident users want to be taught before they try to do real work with the product. And what is the object of being taught? It is to gain confidence. If your teaching is successful, your student will become a confident user who then wants to get on with the job and learn by doing.
In part, confidence is a matter of personality. Some people are naturally hesitant and unwilling to take any kind of risk. These people will always want to be taught. But for most people, non-confidence is a specific and limited condition. I am not confident in my ability to do some particular thing because I don’t have a mental model of how to do that thing. Once I have a mental model of the task, my confidence returns.
The question we should be asking, therefore, is how confident are our typical users likely to be that their mental model fits the tool and the task. If you believe that they are likely to be confident, you should be supporting leaning by doing; you should be writing topics.
Notice that the question isn’t whether the user’s mental model is actually correct. It is the user’s confidence in their mental model, not its correctness, that influences their choice to learn by doing or to seek to be taught. Even if you are confident that the user’s mental model is in fact wrong, and needs to be reset, you can’t address this by creating a textbook. Unless and until the user’s confidence is destroyed by failure to complete a task as expected, they are not going to allocate time to read the textbook.
What this does highlight, is that when you create a whole documentation set in the user assistance model, that documentation has to do more than traditional context-sensitive help would do. It needs to recognize that when the user, in learn-by-doing mode, gets stuck and consults the docs, the topic they land on has to help them recognize if the root cause of their problem is that their mental model is wrong. And it has to do it without being a textbook, because the reader is, at this point, still not willing to read a textbook.
Of course, new mental models are not formed in an instant, nor are they entirely formed by study. Ultimately, they are formed by experience, and so it is by no means necessary for the documentation to drop the reader back into a textbook the moment they realize that there is a flaw in their mental model. They are, in that moment, in a prime position to reset their model through practical, hands-on experience. If the docs can, at that point, push them towards a new mental model, and prevent their confidence from lagging, they can continue to work in learn-by-doing mode, and recourse to the textbook can be avoided.
What this tells me, though, is that there is more to designing and writing topics than simply being brief. A topic has a sophisticated role to play in maintaining and building a user’s confidence, and by subtly and appropriately rectifying their mental model when the time is ripe to do so. This is a subject that I thing merits much thought and study.
What do you think?
That’s a good insight. I agree that a reader’s confidence plays a huge role in determining what he expects to get from the documentation.
The DITA model supports this view. We start with task topics, with which a confident reader can jump right in and learn by doing. We augment the task topics with two other topic types: concept topics (background or “big picture” information — excerpts from the textbook, if you will) and reference topics (quick look-up). These latter topic types serve to teach the reader and build up his confidence to the point where he’s ready to start doing the job.
In short, the topic-based model is flexible enough to support readers who approach the documentation from widely differing levels of preexisting skill and widely differing degrees of confidence.
Hi Larry,
Thanks for the comment. Perhaps you can speak to some of the concerns I have about DITA in this regard.
My first concern is that DITA’s strict segregation of tasks, concepts, and reference may not be the best way to serve readers in this regard. My concern is similar to that expressed by Shannon Greywalker’s blog post “Why minimalist documentation is not always a good match for agile development“:
Suppose Fred is reading an API reference topic because his mental model is that the thing he wants to do has to be done in code, but he really should be reading a configuration reference topic, because what he wants to do is actually done in configuration, not code, in our product. If the API reference topic has had all the concept information removed from it, how will Frank realize that his mental model is wrong and he needs to look elsewhere?
Minimalism is about helping people get themselves unstuck and, like Greywalker, I don’t see how strict segregation of task, concept, and reference accomplishes that.
Secondly, from all I have heard and seen, DITA has problems with rich linking. A number of articles urge people to remove links from their topics to make it easier to reuse them. And I have also heard and read a number of complaints about how much time people have to spend on creating and managing links and link maps. The DITA based documentation I have read seems to have almost no internal linking.
What Frank needs to get his mental model reset is, first of all, some concept material in the API reference topic that triggers the realization that he is on the wrong track, then a link to some appropriate overview material that explains how things work in this product, then links from that material to a description of the configuration procedures, and from that a link to the configuration reference for the details of the particular configuration he needs to do.
But by separating concept material from task and reference, DITA would seem to remove the bridge text, and by removing or minimizing links, it would seem to remove the bridge itself.
Can you suggest how a DITA approach would work for someone in Frank’s situation?
Mark,
Great post, as always. I would though, like to clarify a few points pertaining to DITA. First, in the comment above you seem to suggest that DITA’s strict types can constrain writers, making a minimalist approach difficult if not impossible. That, however, is not entirely true. While it is true that DITA content is generally written in such modules, there is nothing preventing an author from combining and mixing modules in such a way as to achieve, say, a page with both referential and conceptual content.
Another quick point on linking — you point out that many people have complained that cross-references are discouraged in DITA because they can create reuse issues, and while that was true in DITA 1.1, the problem has been addressed in DITA 1.2 with the introduction of indirect linking.
Still, as you point out, link management can be somewhat time consuming, and I won’t argue with you there. I would only point out that, in cases, it is worth the effort. For instance, “soft-linking” can be an elegant solution when adopting an “every-page-is-page-one” approach, but we’ve found that when an author is looking to instruct, the ability to design and maintian a deliberative pathway via links is paramount to guiding users through complex material. Soft-linking, though easier to maintain, strikes me as more of a shotgun approach, where providing clearly defined paths would be far more difficult. Thoughts?
Hi Jack,
Thanks for the comment. Yes, I know that DITA’s types don’t really constrain writers. I don’t really see that as a plus, though. Structured writing should constrain writers. That is rather the point.
I agree that the indirect linking features of DITA 1.2 addresses the link reuse problem at a mechanical level, and will allow people to keep links inline and still reuse the topic. But I doesn’t do anything significant to address the overhead problem. Links are still expensive in DITA, and the iron laws of economics dictate that what is more expensive will be used less often.
You can’t optimize a system for everything, of course. DITA is not optimized for linking. Soft linking, as you correctly point out, is not optimized for dictating a fixed reading order.
I’ll happily agree with you that when an author is looking to instruct, soft linking and Every Page is Page One are not the best tools for the job. My question, though, is not whether the author is looking to instruct, but whether the reader is looking to be instructed.
We may argue that the user would be better off if they would sit down and read the book thoroughly from end to end before attempting to use the product. But they don’t. For as long as we have muttered RTFM under our breath, for as long as we have been aware of the minimalism studies, and certainly for as long as there has been Google, we have know that they don’t.
Tech writers are a lot like parents of teenagers. We want to do everything we can to meet their needs, but we simply can’t get past our exasperation that they will not sit down and listen attentively to the advice we give them. Would they be better off if they did listen? Indisputably. Will they do so? Not a snowball’s chance in June. Our job is to wait for the phone to ring at 3 am and go bail them out of jail.
The question of the moment, I believe, is if they will not read the manual cover to cover, how do we give them the big picture — when they are finally ready for it — in topic form.
Thanks for the reply. First, let me clarify, I didn’t mean to say that structured author doesn’t constrain writers, what I meant is that it doesn’t necessarily constrain the deliverables that can be produced by that content. It is a matter of appreciating the difference between producing/managing content and assembling/deliverying content.
Also, I tend to agree with you, that many readers will not read a manual cover to cover, but I don’t think that we can make blanket statements about users. I think the tendency is not that users do this or that, or even that this set of users behaves one way while another set of users behaves another way. Some people will sometimes want instruction sometimes and will want to learn by doing at other times; and different people will want these things with different frequencies and for different reasons. For that reason, the approach we’ve been attempting to implement is one that provides both kinds of instruction via a tiered delivery model.
For instance, in our case, tier one is guidance embedded directly in the software — very minimal, often task-based, content. From there, users are offered access to a richer, task-based topic available in the help system. And from there, the user is offered access to still more content, but now richer, more conceptual, and often with more well-defined link pathways.
In any case, take care, and thanks again for your insights.
Jack