Topic Based Documentation
What is Topic-Based Documentation?
Topic-based documentation is a way of structuring content in separate ‘chunks’. Each ‘chunk’ is usually called a topic, and it should cover one specific subject. A topic is usually a file, but there are also database systems that use topics, such as Paligo.
If you’ve never written in topics, you are probably used to writing documentation in a single file. For example, user guides written in Microsoft Word are usually one file, with all of the sections and chapters in that single file. The problem with this single-file approach is that it makes it hard to reuse and manage your content.
With topic-based documentation, you write chapters and sections in separate files, so that they can be re-used, like building blocks.
Topics Make your Content More Reusable
There are lots of topic-based authroing tools, but the ones I use most are MadCap Flare and Paligo. With these tools, I write each section in a separate topic. The topic can then be used on its own or added to a group of topics. For example, if I have a ‘Charging the battery’ topic, I can use it in one manual or in lots of different manuals. The same topic is used in each one. (The example below shows a table of contents in MadCap Flare, which has a separate file for each topic).
This modular approach is better for documentation because it makes it quicker to create a suite of manuals that have ‘common’ content. The topics can be used in different manuals as needed, and there is much less work involved when it comes to updating the content. If I need to change a topic, I make the change once, and it updates wherever that topic is used. Another benefit of topics is that they help writers stay focused on a single subject, as a topic should only cover one subject, such as one concept or one task.
Translations are also easier to handle with topics. That’s because translators can easily identify which topics have changed or need to be translated.
But to write topics successfully, you need to understand how your content might be reused. And that can mean compromising in your content a little, to make it more generic and more suitable for use in other topics. (There are usually conditioning or filtering tools for showing/hiding content that is specific to certain versions, which helps a lot).
Standalone Topics = Better User Experience
One of the tell-tale signs that a document hasn’t been written by a trained technical author is that the content is linear. It relies on your customers reading content from the start, in sequential order. It also relies on them remember ing what they have read in ‘earlier’ sections so that they can make sense of ‘later’ sections.
When was the last time you picked up a manual and read it from front cover to back?
People read manuals and use online help systems by diving straight into the sections that are relevant to their problem. If they go to a section and can’t understand it because it relies on knowledge learned in ‘previous’ sections, you have a problem. Because in this situation, will they read ‘earlier’ content or will they take the easier option of calling your tech support?
With topic-based documentation, writers need to think of content as independent ‘chunks’ of information. This helps to make the content more standalone, so customers can dip in and out of the information in a random order. So it gives a better end-user experience.
One thing I should make clear is that standalone content should contain navigation to other related information. There is no concept of ‘earlier’ and ‘later’ in the document, but we still need to direct users to relevant content.
Unfortunately, not all technical writers understand topic-based documentation, and so some bad habits, such as writing linear content, have became common practice. If tools that use topic-based documentation help to make them think differently, it can only be good for your customers, your business, and all of us writers who are tasked with ‘fixing’ linear content.
Yes, I Do Topic-Based Writing
Paligo and MadCap Flare are my preferred authoring tools, and they both use topics. But even when I’m writing in Word or FrameMaker, I take a similar approach – making each section as standalone as possible.
I’ve worked with topic-based documents for many years and can turn linear content into reusable, modular content with ease.
Let's Get your Content Started
Click the button below to get in touch.