What is Topic-Based Documentation and How do you Write it?

Topic-based documentation is a way of writing documentation in stand-alone chunks, which are usually stored in separate files (or topics). Each topic focuses on one specific subject, and this applies to pretty much any type of user documentation. To illustrate the point, I'll avoid the obvious software example and go for something more unusual...let's say you are writing a manual on boxing. To use a topic-based strategy, you might have separate topics for: throwing a jab, defence after throwing a jab, jab to attack, jab to retreat, defence against a jab, jab and move. Each of these topics would focus only on their specific subject and they would come under a section on Jabs.

Topic-based documentationTypically, a topic explains 1 concept or provides instructions on how to complete 1 task. A 'how to' task may include a small amount of concept information, but only enough to remind the user about why they need to perform the task or what happens after they complete the task. It is important that the topic does not stray off the subject, because the whole point of topics is that they are minimalist as this lends itself best to re-use in other documents. For example, let's say the boxing manual is part of a series of manuals on combat sports, and there are other manuals on kickboxing and mixed-martial-arts. Each of the jabs topics may also be relevant to the Kickboxing and MMA manuals, so the 'Throwing a Jab' topic could be used in all three manuals. But this is only going to be possible if the 'Throwing a Jab' topic stays on subject - if it starts to wander off into the history of boxing or other boxing techniques, it will not be suitable when used in the other manuals. If it only focuses on throwing a jab and nothing else, it can be used in all three without becoming irrelevant or incorrect.Does this mean your topics have to become so generic that they are not as useful? No, but you do need to be disciplined when writing your topics. Each topic has to work as a stand-alone piece without any reliance on other topics. If you can read it on its own, without referring to any other part of your documentation , and it still makes sense, you're on the right track.But what if you want to include supporting information to a 'how to' process? That's where linking comes into play. That supporting information should exist in one or more topics too, so you include links from the 'how to' topic to the conceptual topics that relate to it. This works better for your readers as more experienced users don't have to wade through information they already know and novice users can follow the links to the topics they need.If this blog post was following the topic-based principle, the 'What is Topic-Based Documentation' section you've just read would be a topic in its own right, and would link to the related topics below.

Where Can you Use Topic-Based Documentation?

The leading Help Authoring Tools (HATs) all require you to use a topic-based strategy, as does the DITA mark-up language. But you don't need to be using the latest tools to write your content in topics - you can make each section of a Word document a 'topic', just as easily. Okay, so a Word document isn't going to give you the single-sourcing features of Flare, Robohelp, or a DITA editor, but if you apply the same principles, you can create sections that can be copied and pasted and re-used without changing them. If you really wanted to, you could save each 'topic' in your Word manual as a separate file.If your documentation has been created by knowledgeable technical writers, you'll probably find that your manuals are already in a format that lends itself to topic-based documentation. Because the reason topics work is that they provide readers with what they want - a specific answer to a specific question. Think about it - do you read a manual from front to back, like a book? No, you dip-in to the sections you need, as and when you need them. That's why topics work - they don't rely on the reader knowing what comes 'before' or 'after' the information.

How to Write Topics

Writing in the minimalistic approach that is needed for topics requires some discipline and skill, and it's not something that every technical author seems to understand. Certainly, I've seen work by writers with over ten years' experience struggle to get to grips with the idea. For them, the biggest problem seems to be understanding the non-linearity of topic-based help. "But the user already knows that from a previous section." No, they don't. Because there is no previous section or next section - there is only the current section and the sections it links to.So when you are writing a topic, try to think of it as a landing page. In that one topic, you need to tell the users how to do one specific task or you need to explain one concept. You can link out to other related topics (but you may need to consider how you link out if your topics will be used in other projects, especially in DITA).Think about:

• What is the topic about? What is the one thing the reader wants you to tell them? If there is more than one thing, should your content be split into separate topics?
• Are you going off-topic? Stick to covering the subject and don't go off at tangents.
• Is the amount of background information you are providing too much?Including one or two lines of supporting information in a topic can help users understand why they need to perform a task and what the outcome will be. But if you are going beyond just a couple of lines, you should hold back and link to a relevant topic that explains the concept (you might need to write that topic if it doesn't exist).
• Other information the user needs.You don't need to include links to every part of your product or service, as you can safely assume that the reader will look for help on those separately. But you should link to any related sections so that from your topic, the user can navigate to all of the other topics that provide the 'full picture' of the subject you are writing about.
• Does the topic work as a stand-alone section? Get someone who doesn't know about the product/service/feature to read it and see if they think it makes sense.

Why Should you Use Topic-Based Documentation?

Writing in topics will save your organisation money, improve the quality of your documentation, allow your writers to re-use content, and make it much easier to update your manuals and help. For more details, see my 5 Benefits of Topic-Based Documentation post.