Taking a topic-based approach to your documentation can improve the quality of your manuals and online help, reduce your documentation costs, and make it easier for your writers to produce and update content. This approach is not new, but implementing it with the latest authoring tools, such as Flare, Robohelp, Confluence or an XML editor like oXygen, does give you the added benefits of being able to manage single-sourcing. It’s not just for new tools though – you can take a topic-based approach with traditional Word, FrameMaker, or InDesign manuals and reap the benefits too.
#1. Gives Your Customers the Information they Want
Very few people read manuals or help from the first section to last in order. That’s why documentation written in a linear structure just doesn’t work – you can’t assume that your users have read ‘earlier’ sections. The chances are that they just don’t have the time to read all the content! So how do people use manuals? Well, how do you use a manual or help? Let me guess…you only use the documentation when you have a specific problem, and you are looking for a specific answer to that problem. That’s what your users want too, and topic-based documentation gives them just that, because each topic focuses on a specific concept or set of instructions and works as a stand-alone article.
When your technical writers are producing topics, they need to use a more minimalist style and have to really think about the amount and type of content that goes into each topic. They will also need to think about potential re-use, so there should be no rambling off-topic or shoe-horning conceptual information into a task. This all means that your users get to read content that is stripped down to just the information they need, with less repetition. It gets straight to the point.
#2. Topics can be Re-used in Other Projects
As topics should be written as stand-alone content that is focused on one task or concept, they can be used in other projects with little need for alteration. This single-sourcing of content can dramatically reduce the amount of time it takes to produce documentation.
#3. Easier to Update
Each task or concept related to your product or service should be documented in its own topic. So when the time comes to document a change to a feature, there is only one topic to change. There’s no need for authors to spend time searching through documents for any reference to the feature that has changed.
At the moment, you may be taking the traditional route of producing FrameMaker or Word documents and converting them to PDFs. There’s nothing wrong with that, but if the documents are not written in a topic-based style, they are going to be more difficult to convert into online help, web-based help, or wiki articles in the future. Importantly, if they rely on users reading them in a linear fashion, they are not meeting your users’ needs.
#5. Reduce your Costs
Content that is written in ‘topic’ style sections will reduce your documentation costs. Documentation that is organised into distinct topics takes less time to update and can be re-used in other documentation projects. And as we all know, time is money.
If you’d like to find out more about topic-based writing, see my other post What is Topic-Based Documentation?