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.
Links to sections:
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.
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:
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.
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. Instead of writing each section in a linear fashion, as if you were writing a manual from front cover to back cover, you write each section as its own topic. Ideally, you want each topic to make sense when read on its own, with links to other topics where the reader may need more information. Then, you create a publication and add a collection of topics to it. This is where you put the topics into a sensible order and assemble your user guide.
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.
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.
When you're writing topics, there are several things you need to keep in mind, including:
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.
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:
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.
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.
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.
Registered Number: 08029184
Straygoat logo design by Bristol graphic designer, Nik Jones.
© Straygoat Writing Services Ltd.