You can’t size topics for specific information needs

One of the biggest traps in topic-based writing it the attempt to size topics so that each one meets exactly one user information need. It is tempting to suppose that this is the point of topic-based authoring. If the book is the wrong size because people only use them to look up bits of information, rather than reading them through, isn’t the point of writing topics to make the topic contain just the information the reader needs in the moment (so that they will read it through)? Thus we envision our reader’s needs mapping to our topic sets like this: read more

Design for Wayfinding

Much of the time we spend with technical documentation is concerned with wayfinding. That is, it is not about performing the actual operation, but about finding which operation to perform, and finding the piece of content that describes the operation in a form that we can understand.

Note that there are two distinct components to this description of wayfinding. It is tempting to think of wayfinding purely in terms of finding the right piece of content. But simple content wayfinding really applies only in cases where the user it thumbing through a well known and well used reference work. That is, in cases where we know exactly what we are looking for, and merely have to locate an individual data point. read more