topic-based documentation

Many of the leading technical authoring tools use a topic-based approach to content. This is a more modular approach to creating user guides and help systems, and if you are used to writing Word documents, moving to topic-based writing may seem odd at first. Here, I’m going to look at the many benefits of topic-based writing, how it works, and how you need to approach writing in topics.

It’s quite a long post, so I’ve included links to the sections below.

What is Topic-Based Documentation?

Topic-based documentation is a way of structuring content in separate ‘chunks’. So instead of having all of your content in sequence in a single file, such as a Word document, you have lots of separate pieces of information. You can then build a user guide or help system by choosing which topics to include.

What’s the point in doing that? Let’s take a look at the benefits.

Benefits of Topic-Based Documentation

There are lots of benefits to be had from a topic-based approach, especially if you have an amount of repetition in your documentation. Here are the main ones:

  • It makes you think carefully about the content you are writing. If you are writing topics correctly, you have to focus on one thing, so there’s no cramming in extra bits of information or going off on a tangent.
  • It can result in a better end user experience. They can go straight to the section that contains the information they need, and it should make sense without having to read ‘earlier’ topics. (I don’t like the word earlier, as it suggest linearity, which shouldn’t come into play with topic based documentation…or documentation in general, in my opinion).
  • It can reduce the amount of time it takes to create new user guides that are similar to existing user guides.
  • It allows you to easily create guides that are tailored for different audiences.
  • It means you can use the same content in different types of output. For example, you could use the same ‘specification’ topic in a user guide, training content, and marketing document.
  • It usually goes hand-in-hand with other powerful authoring features such as content reuse, variables, and conditional text (see my content reuse article). 
  • It makes it easier to create, manage, and update your content. So it can reduce your documentation costs.

But most of these benefits only apply if your content has lots of sections that need to be repeated. That’s often the case with technical documentation, certainly when you are responsible for writing content for a range of related products or services. But you’re not going to get much benefit out of topics if you don’t have repeated content or you’ll never need to use ‘chunks’ of content elsewhere. 

Will you need to change the way you work if you switch to topic-based authoring? Possibly, but the amount of change will depend on how you author your content now. Let’s take a closer look at how it works.

How Does Topic-Based Documentation Work?

There are lots of authoring tools that use topics, but they don’t all work in the same way. However, the general principle is pretty much the same for all of them.

Topic-Based Documentation - Step 1 Create the Topics

You start by writing your ‘chunks’ of information in separate topics. Each topic could be a file or it could be a location in a database, depending on how the tool works. When you write your topics, you need to make sure that each topic focuses on one thing, such as answering one question, explaining one concept, or providing one example. This is important because each topic may be used in lots of different user guides, so if you start to drift off the point, you may introduce concepts or features that are irrelevant in some places.

Topic-Based Documentation - Step 2 Create the TOC

When you have your topics, the next step is to decide which topics are going to be included in your publication. The publication is what the end users get to see, for example, a HTML5 help system or a PDF. The way to set up the publication varies depending on the tools you are using. But the general idea is that it is like creating a table of contents or a ‘map’ of the topics to be included.

You can use topics in as many publications as you need. For example, if you have a ‘Safety Information’ topic, you can add that same topic to every user guide that your company produces. You write it once, in one place, but can use it in lots of different places.

Topic-Based Documentation - Step 3 Publish

The final stage is to publish your content. In this stage, the authoring tool copies the content from the selected topics and generates the publication (the output). So the original topics remain as they are in the authoring tool. The authoring tool generates publication files that contain the same content as the topics, and it is these publication files that the end user gets to see.

Example:

Imagine that you are responsible for writing the user guides and specification sheets for six different pumps. The pumps are all part of the same range, so they share a lot of common features.

If you were writing the user guides in a non-topic tool, such as Word, you would perhaps write one user guide in full. Then, for the other user guides, you would create new files and copy and paste the repeated parts to each user guide. No problem so far. But what happens when you need to update some of the content? That’s six lots of updates , so lots of time-consuming copying and pasting. I don’t know about you, but I HATE doing the same thing over and over. Repeat work like that is also prone to user error.

Now, let’s see how that would be different with topic-based writing.

Instead of creating one user guide and then copying and pasting, you would create all the topics you need, once in one place. For the first user guide, you would create a publication and add all of the topics that it needs. For the second user guide, you would take the same approach – create a publication, add the topics that it needs (which would include some of the same topics that were in the first user guide). You would do exactly the same for all of the user guides. So the big difference is that your content exists in one place – in the topics – but it can be used many times in different publications.

When you need to update the content, you make the updates once – to the topics in the authoring tool. Then you re-publish the user guides. The published content is updated with the new content automatically (as the authoring tool takes the content from the topics to generate the published files). That’s where topic-based documentation really helps to reduce the time, effort, and cost of managing documentation – it makes bulk editing easier and faster.

Do You Need to Change Your Writing Style for Topic-Based Content?

Yes, but the amount of change might be negligible, depending on how you already work. I’m lucky, because I was always taught that nobody reads a manual from front-to-back like a book. So even when I was working in Word or FrameMaker, creating non-topic content, the stuff I was writing was well-suited to the transition to topics.  Each section dealt with one specific subject, was designed to work as a standalone piece, and had cross-references to any other sections that were relevant.

If you write user guides in the same way, moving to a topic-based system is going to be much less of a leap. You’ll need to get used to content being in lots of different places and you might need to gain an appreciation of writing content for use in multiple places. But it isn’t that different to what you are doing.

Unfortunately, there are plenty of technical writers who approach user guides like a book, and create linear content. This just doesn’t work with topics (and I’d argue it doesn’t work with documentation anyway – if you need instructions to do something, the chances are that you need them now and don’t have the time (or the need) to read several other chapters first.

If you have linear content, you’re going to have to rework it for topics. Especially if you are using an online help publication, because when a user brings up a help topic, content that mentions ‘as discussed earlier’ or ‘as you learned previously’ is meaningless, as it doesn’t match their experience.

What Do You Need to Consider when Writing Topics?

When you’re writing topics, there are several things you need to keep in mind, including:

  • Topic-based documentation requires a modular approach. Instead of writing content in a sequence, you need to write standalone chunks of content that make sense on their own. The end user should not have to read ‘earlier’ sections to understand a topic.
  • A topic should have one focus , such as answering one question or explaining one concept.
  • A topic can be included in more than one publication (PDF, HTML5 Help, Ebook, etc.).
  • When you make a change to a topic, that change applies wherever that topic is used. (But only after you republish). Let’s say you have an example that is used in 5 different user guides. You decide to change the example, so you edit the example topic. The change you make in the example topic will apply to all 5 user guides, as that same topic is used in them all.
  • You might need to COMPROMISE. Yuk. One of the downsides to topics is that because they can be used in many places, what you write needs to make sense everywhere it is used. That may mean you need to make the content a little more generic than you normally would. Alternatively, you may decide to create separate topics in that situation – that’s fine, but be aware of the extra workload involved with updating it. Sometimes it is better to have two versions of the content in the same topic, and then use conditions to show/hide one version depending on the output.
  • If you are using topics, you should really spend some time to learn about content reuse , conditional text, and variables. These features/concepts are all related.
  • If you work as part of a team, make sure that topics are easy to find and are clearly labelled with a consistent naming system. If other writers can’t find a topic, they may create a new one, which could duplicate your content.

If you would like to know more about the types of things you need to consider when writing topics, I recommend Mark Baker’s book, Every Page is Page One.

Is Topic-Based Documentation Right for You?

If you have documentation that contains a lot of repetition, then topics will make it easier to manage your content. The types of content that are often repeated, either in one document or across a suite of documents, include:

  • Safety information
  • Copyright information
  • Contact details
  • Examples
  • Product specifications
  • Product overviews
  • Disposal and recycling information
  • Statutory and regulatory information
  • Technical support contact details.

Topics are less useful if you don’t have a lot of repetition or if you know there is only going to be one document. For example, I recently documented a software product and the client wanted a video game style manual. This had to be a very brief user guide (less than 20 pages), and there was no intention to have other guides. So for that project, I used InDesign. There was no need for topics or content reuse.

Over to You

I’ve been using topic-based authoring tools for many years now, and they really help me to work quicker and easier. In fact, my heart sinks whenever I have a project that requires a more traditional approach. What do you think? Can you see the benefits of a topic-based approach? Do you find the modular approach to writing confusing or daunting? Let me know in the comments.

Techncial Writer, Craig Wright

Craig Wright is an experienced technical writer based in Chesterfield, UK.  He hates writing about himself in the third person, so I shall stop now.

Always interested in new content writing opportunities. Remote working preferred.

Share This