To get managers behind a migration to topic-based authoring (TBA), focus on benefits and savings.
Last week, I had the opportunity to present TBA to senior managers. The main objective was to show why it was a good idea to change our documentation method, even though we will have to rewrite and reorganize our contents. Here’s a walk through my presentation. Maybe you find it useful to convince managers – or any non-writers – to support you in implementing TBA.
I present the speaker notes and explanations instead of the actual slides which only contain the phrases in bold below. This post describes the first three slides. The next post within a week will cover the second three slides, so be sure to check back.
What is topic-based authoring?
I use a simple definition plus 5 principles and explain why each of them is important:
Topic-based authoring chunks documentation into topics.
- Self-contained, they can be read alone, but stand in context with others
- Task-oriented, they serve users by explaining, instructing or informing (instead of serving the product)
- Reusable (potentially), for example, in online help and manuals
- Output-independent, they can appear online, in PDF or print
- Easy to manage, that is, to write, review, edit, publish, translate (in bundles)
What do topics look like?
An example illustrates the 5 principles in action. I show a screenshot of a rather obvious sample topic of a procedure in the context of the table of contents (a design draft will do, if you don’t have a screenshot). I explain:
- How the topic is self-contained
- How the links to related topics create a context
- How it is task-oriented by instructing the user to do a certain thing
- How it can be reused in the online help and a user manual (online or in PDF)
- How a bundle of conceptual and procedural topics can be processed faster than a complete user manual without losing the context to review, edit and translate it properly
– The main argument, however, is why we need to change and implement TBA. So I have three slides of benefits and challenges, one about each group of stakeholders of the documentation: The customers, the writers, and the owners, that is, our company.
Note that just doing topics forgoes most of the benefits; you need to do them well. This requires a solid structure and tagging within your topics, else you lose a lot of reuse potential. It also requires a well-structured collection of topics where conceptual and procedural topics complement each other, else you lose the transparency of your coverage.
Benefits and challenges for customers
Easier to use. The customers of our documentation are external and internal users alike. For either group, the modular, chunked documentation – if done well – is faster and easier to use, since substantial information has one place and is easy to find under a clear, well-written heading.
More reliable (possibly). As a side benefit, clearly structured documentation may also strike customers as more reliable. To me, it seems that an obviously missing topic is more forgivable than a hard-to-navigate content swamp where you frequently cannot find what you’re looking for. But I have no evidence for this claim.
Harder to read? The challenge to customers can be that it is more tedious to read the documentation front-to-back. Even though we have some manuals today which read like textbooks, that is not our primary use case. So this may be the price for better findability and usability.
More to come…
The next post will feature the second part with the other three topics:
- Benefits and challenges for writers
- Benefits and challenges for companies
- Actual savings from topic-based authoring