To get managers behind a migration to topic-based authoring (TBA), focus on benefits and savings. This is the last post in a two-part series. Find the beginning and background in part 1.
I present the speaker notes and explanations instead of the actual slides which only contain the phrases in bold below.
Benefits and challenges for writers
Make documentation efficient. For technical writers, the structure within topics and across all topics makes writing topics more efficient because you spend less time stressing over what goes where and over layout.
Make documentation transparent. The structure of the topics collection as a whole makes content more transparent: It’s easier to spot a missing topic, if each setup procedure (how to set up stuff) is accompanied by an operating procedure (how to use what you’ve just set up) and by a concept topic (what is that stuff you’ll set up and operate). Thanks to their structure and smaller units, documentation efforts also become easier to estimate – though maybe more tedious to report on in their details.
Collaborate more easily. The structure also makes it easier and faster for writers to collaborate on writing, reviewing and editing each other’s topics, again, because it’s quickly obvious what belongs (or is still missing) where.
Assume new tasks and responsibilities. Challenges for writers are learning a whole new range of tasks and responsibilities, from “chunking” subjects into topics and making sure there is one (main) topic for each subject to interfacing nicely with the topics of colleagues to peer-editing other people’s topics. On the other hand, most writers no longer have to double as layouters and publishers, since that role is usually in the hands of a few people.
Migrating legacy content. Another challenge is, of course, to migrate all existing contents into topics. However, this is a one-time effort, while the benefits of clearly structured topics keep paying off.
Benefits and challenges for companies
Of course, the benefits and challenges for writers affect the company as a whole. But there are additional effects to the company owning topic-based documentation.
Leverage corporate content. Cleanly structured (and tagged) content in topics is much easier to leverage as part of a corporate content strategy. (Did I mention this was a presentation for managers? Hence the verb “to leverage”…) After all, there are other teams who may well hold stakes in some documentation topics or parts of them:
- Product management or even Marketing may want to reuse parts of concept topics, such as use cases.
- Training could reuse procedural topics.
- Quickly searchable documentation can improve customer services – or any type of performance support your company may offer.
Make recruitment more efficient. Clearly structured, topic-based documentation will make it easier on a company to find and hire professional, qualified technical writers – and help new writers get up to speed faster.
Savings from topic-based authoring
Your mileage will vary, depending on your current deliverables, processes and tools. However, from the case studies I’ve seen around the web and at conferences, our numbers are not unusual. Savings are in hours for writers who apply topic-based authoring compared to their earlier efforts without TBA.
- Writing Release Notes as usual – saving 0%
- Writing Online Help, largely reusing Release Notes topics – saving 45-60%
- Writing new User Manuals, by reusing some topics from Release Notes or Online Help – savings unknown
- Updating existing User Manuals, by reusing Release Notes topics – saving 60-75%
To read more about measuring efforts and costs, see my previous posts about:
About topic-based authoring, I recommend these two books:
- Kurt Ament, Single Sourcing: Building Modular Documentation
- Gretchen Hargis, et al., Developing Quality Technical Information, chapter 8 “Organization”, pp. 215-244.
Would these arguments convince your managers to support you in moving to topic-based authoring? What other arguments might it take? Should such an initiative to restructure documentation come from writers or managers? Please leave a comment.