User Confidence and Topic-Based Writing

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? read more

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. read more

The Reader is the Enemy

Noz Urbina asks, Is Communication Mired in the Past? Well, yes, obviously. Most of the tech comms world is still making books in FrameMaker. But also no, because the problem is more profound than the words “mired in the past suggest”. People get mired in things through carelessness or misfortune. They want to get out, but they can’t. Technical communications isn’t mired in the past, it is entrenched there, gallantly, if with dwindling hope, guarding the battlements against the encroaching hoards of readers. read more

Princes of Erudition?

Just back from JoAnn Hackos’ CMS/DITA conference, where it became clear that even in a conference dedicated to a topic-based authoring methodology, most people are still writing books. Certainly, they are writing them in the form of topics, but then stitching them together into books. The fundamental product is still a book.

Too little information

Were I asked to characterize the human condition in a sentence, I might choose this: to be human is to make decisions with too little information. All our decisions, great and small, are taken without adequate information: getting married, buying real estate, having children (this especially), saving for retirement, choosing the best route for a journey, taking a job, or hiring an employee. We don’t know nearly as much as we would like to in making any of these decisions.

Deconstructing Pizza

My daughter use to eat pizza one ingredient at a time. She would patiently sit and take her slice apart, making separate piles of pepperoni, green peppers, olives, cheese, and crust. She would then eat each ingredient in turn.  I am reminded of the bizarre (and short-lived) practice when I see how many people do topic type design (or at least, how they talk about it).

Designing topic types, I read in many articles and presentations, is about dividing information up into different types. The number of types proposed varies, but the principle always seems to be the same: there are distinct types of information, and the goal of topic design is to pick them out of your content and make separate neat piles of them. read more