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