This guest blog post was written by Neil Perlin. Neil has 4 decades of experience in tech comm, with 35 years in training, consulting, and development for various online formats and tools including WinHelp, HTML Help, CE Help, JavaHelp, WebHelp, Flare, and more.
If your background is in writing for print, you’ve probably heard of “topic-based authoring” but may not be familiar with it. This article will introduce you to the high-level concepts and some details of topic-based authoring, particularly for use in your technical documentation. This also begs the question, what is technical writing and how can it benefit from topic-based authoring?
At a high level, topic-based authoring is simple. Rather than writing a “book” as one long document, you write a bunch of small chunks of information – “topics” – that can be strung together to create that “book”. Why do this?
The main benefit of a topic-based approach is the flexibility of publishing. Let’s say that you write a user’s guide for a modular product that assumes that a user has bought modules A and B. But what if a user only bought module B? And, to complicate things, your company wants to only describe the module(s) that a user has bought. You have to remove all references to module A. But what about users who only bought module A? You now have to make a copy of the user’s guide and remove all references to module B. And you have to maintain both versions, remembering what changes to make in one book, the other, or both. It’s easy to forget.
Topic-based authoring turns this model on its head. Instead of creating one book and then customizing it for different audiences, you create topics, some applying to all modules, others only applying to module A or B. Now, when you need to create a user’s guide for a buyer of module A, you simply string together all the individual topics that apply to all the modules, plus those topics that apply to module A only, and you’re done.
Implementation isn’t this easy of course. But, moving to topic-based authoring and publishing is easier than you might expect. Much of the work is done up-front to define how to write, how to create topics in general, how to select the topics for a specific document, and who the possible audiences are. Let’s take a brief look at these issues.
Writing – Like “Regular” Writing but With Exceptions
Some of those exceptions include…
Information must be as self-contained as possible. When it can’t be, you have to provide continuity through hypertext links. In print, for example, you can mention a concept and say “as described above”. You can’t do this in topic-based authoring because the “above” reference may now be in a different topic. You have to replace that reference with a hypertext link – easy to do but a different way to think and write.
There’s also the loss of linearity. You can no longer assume that readers will read procedures 1, 2, and 3 in sequence if each procedure is in a separate topic. You have to assume that a reader might see the topic for procedure 3 first and decide what to do if they have to read procedure 1 first.
More on content authoring: What is structured authoring?
Topic-based authoring’s flexibility also means topics may be used in multiple formats across multiple outputs, such as print and online, via large desktop displays, tablets, smartphones, etc. The writer must take this into account. Because if a topic is viewed on a smartphone, for example, you may want it to be short and tightly written. This may take more effort; the benefit is that the same topic will be easier for users to read and understand no matter where it’s displayed.
You may also have to account for wording differences between different display formats, such as saying “Click…” when the material appears in print and on large monitors but changing that to “Tap…” when the material appears on mobile devices.
None of these exceptions are show-stoppers. You just have to plan for them during the content development process and use single-source authoring tools that support that planning.
Defining Topic Specifications in General
Defining topic specifications in general means deciding on the level at which to break your material into new and separate topics. One way to do this is to look at the table of contents for a book you’ve created, review the heading and sub-heading levels, and use that as a guide to creating topics – self-contained chunks of information. That’s fairly easy to do.
What can complicate this within a doc group that wants to use topic-based authoring is the fact that different writers will write or organize the same material in different ways; different writers have different “voices”. However, one of the benefits of topic-based authoring is the ability to share the same content between different books. Doing so requires standardization of the material – topic chunking and language. If two authors write similar material differently, the standardization will be more difficult but it’s worth it. However, be aware that some authors will rebel at the standardization.
Defining What Constitutes Topics for Specific Documents or Material
This will obviously differ for different material, but there are cases where this can lead to useful, even strategic standardization. For example, let’s say that authors 1 and 2 each write a description of the warranty for their company’s products. The warranty is the same for all products, but each technical writer describes it slightly differently. Now there are two warranties in circulation, and it may not be clear which one is correct. Topic-based authoring says that there’s one warranty description, with a clearly identified author, that can be used in multiple projects. The result? Ownership and accountability. One task in switching to a topic-based authoring model is to identify opportunities like this.
Defining Your Audiences and the Information They Need
This is usually easy. When learning how to write technical documentation, look at the types of documents you create and who they’re for. For example, a sales guide used for the US and Canada but with different material for each one equals two audiences. You then identify what that different material is. This is also usually easy; you already know most of the differences. It’s just a matter of verifying that you’re right and of looking for differences that you missed.
Solutions That Make Topic-Based Authoring Easy
Various solutions support topic-based authoring. MadCap Flare supports topic-based authoring as its core functionality, along with “less-than-topic” based authoring using features like snippets and variables for repeated chunks of content and “micro-content” to provide users with highly focused search results…Learning to use solutions like Flare is surprisingly easy (mechanically speaking). The free online introductory course is completed in a day, at the end of which attendees, while often still tentative, are creating projects and outputs. The complexity lies in changing how you write, how you define specifications for your topics, and managing what can turn into complex projects. But when used and managed carefully, topic-based authoring offers enormous power and the ability to future-proof your writing for almost any new format and platform that appears. If you haven’t switched to topic-based authoring yet, it’s worth a close look now.
