Topic Based Documentation

Process Writer - Craig Wright Technical Author

Craig Wright

Hi, I'm Craig Wright, an experienced technical writer in Chesterfield, Derbyshire. I write using a modular approach and have experience of topic-based documentation.

Are you puzzled by the term 'topic-based documentation'? It is something of a jargon term in the technical communication industry, and all it means is that your content is written as smaller chunks of information that are stored in separate files. These are called topics. So when you see 'topic-based' it means that the content is in lots of separate files rather than one big file, which is usually the case with a manual written in Word and other word processing packages.

Of course, there's more to it than that, as I'll explain in the following sections. But as you read on, try to keep that idea of lots of files instead of one file in your mind - it is that modular approach to technical writing that makes topic-based documentation so important.

To find out more about topic-based documentation, see the sections below:

As an experienced technical writer, I've worked with topic-based products for many years (I mostly use MadCap Flare and Paligo these days). I'm skilled at writing modular content, and know how to structure content for reuse. Hopefully, you will find the information on this page helpful, and if you need more advice, or would like to hire me to write or organise your topics, please get in touch. Click the button below and complete the form to let me know what you need and when you need it by. I'll get back to you as soon as I can.

What is Topic-Based Documentation?

Topic-based documentation is when information is written as modules, rather than as a single file. For example, if you think of a traditional manual that is written in Microsoft Word, the entire manual is contained in a single .doc file. With topic-based documentation, the approach is different - each section of the manual is created as a separate file, usually called a topic. Each topic should cover one specific thing, such as a single feature or a single task.

There are different approaches you can take with topics. You may decide that each topic is to cover a single subject, and so you could have the concept, a task, and references all in the same topic. Or you could break the subject down into separate topics, where the concept is stored in one topic, the task is in another topic, etc. There is no right and wrong way to do it, but you do need to think about content length, especially if the topic is going to be read on a mobile device. You also need to think about content reuse, as it may need to reuse parts of a topic in other projects, and this is more difficult if they are all in one topic file.

topic-based documentation

There are different approaches you can take with topics. You may decide that each topic is to cover a single subject, and so you could have the concept, a task, and references all in the same topic. Or you could break the subject down into separate topics, where the concept is stored in one topic, the task is in another topic, etc. There is no right and wrong way to do it, but you do need to think about content length, especially if the topic is going to be read on a mobile device. You also need to think about content reuse, as it may need to reuse parts of a topic in other projects, and this is more difficult if they are all in one topic file.

Many of the leading technical authoring tools use a topic-based approach, including MadCap Flare, Paligo, and Adobe RoboHelp.

Benefits of Topic-Based Documentation

The main benefits of writing with an authoring tool that uses topics are:

  • Topics make it easier to reuse content. This will save you money and time.
  • Writers need to plan and write standalone chunks of content. This will improve the quality of your content and the end-user experience.

Content Reuse

Let's start by looking at content reuse. I'm not going to go into great detail here, as I've discussed it on another page, but with most tools that use topics, there are also features for reusing content. This can save you a lot of time and money when it comes to creating new documents and updating your existing content. As the name suggests, content reuse allows entire topics or smaller parts of your content to be stored as one file, but used in lots of different places. For example, if you have a series of similar products, you can build their manuals from the same collection of topics, and add/remove extra info where needed. And if there are sections that need to be repeated in the same manual, there are usually features for sharing smaller 'chunks' of content too.

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 order, and they need to remember what they have read to make sense of 'later' sections. Of course, very few people read technical documentation in the same way as a book. 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, how many people will go back and read all of that 'earlier' information? Not many, because it is just too much work. It is easier for them to call your tech support.

With topic-based documentation, the fact that content is stored in different files helps writers to think of content as standalone. Because there is no longer any guarantee that the topic they are writing will always be in the same manual as the 'earlier' topics, the writer has to start breaking away from that linear way of thinking. As the content they write becomes more standalone, it is better suited to users dipping 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. If the reader does need to get extra information that is stored in other topics, the writer needs to include cross-references to it. There is no concept of 'earlier' and 'later' in the document, but we still need to direct users to relevant content.

Writing content as modules is not a new idea. I did most of my technical writing training in the 90s, before topic-based documentation was widespread, and the idea of writing standalone 'chunks' was seen as best practice back then. I've spoken to older technical writers, and they said it was the same back in the 60s too. The problem is that not all technical writers have studied technical communication, 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.

Struggling with Topics? Let me Help

If you are finding it difficult to work with topics or have a project that would benefit from my experience, I'd love to hear from you. I've worked with topic-based documents for many years and can structure your content and turn linear content into reusable, modular content with ease. You know what to do - hit the contact button and get in touch. Let me know what you need, what your timescales are, and if possible, how many topics you have. I'll get back to you as soon as possible.

Speak to you soon.