Structured Writing and the State of Flow

Image: Evgeni Dinev /

It is well established that we are happiest and most productive when we are working in a state of flow. Accordingly, any interruption of the state of flow can have disastrous results for productivity. The interesting question to me is, what constitutes a interruption, and what is part of the flow.

Is fixing a bad page break an interruption of the writer’s flow, or part of it? What about looking something up in the style guide? What about searching the CMS for a topic to create a link to? If, like me, you answer that these things are all interruptions to flow, not part of the flow, perhaps you will agree with me also that by and large tech writing groups are not set up to make writers as productive as possible. read more

Topics and the Big Picture

Writers often express the concern that topic-based writing cannot handle the big picture. Topics, they complain, don’t provide a way to tie everything together. Thus users get lost in a sea of topics, can’t understand the system as a whole, and can’t figure out where to start.

If you formed your topic set by slicing up a book, then the above is probably an accurate picture of the result. Scattered fragments of a book generally don’t do as good a job as the intact book. No wonder that so many writers, having split their books into topics,  hurry so quickly to stitch their topics back together into books, leaving themselves, in terms of information delivery, right back where they started from. read more

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