Resources‎ > ‎Articles and Books‎ > ‎

What’s the big deal with topics?

Think topic-based writing is the next big thing? You could be right. Even if you are not converting to DITA, you can take advantage of the benefits of writing in topics instead of chapters. And if you are starting to write with DITA, do it right, from the start.

What’s the big deal with topics? They do a few major things:

  • Separate content into types: Users will no longer have to hunt through conceptual information to find the “how to”. And forget wading through customizing a feature when what they really want is command descriptions. Have you ever watched your users flip through 50 pages of important information and then complain that nothing’s there? By writing in topic types, you meet your users’ requirements, matching the way you write with the type of information they’re looking for. Users get the visual cues they need to identify the type of information.
  • Create digestible nuggets: Everyone knows readers don’t read, they skim. Cut down on the skimming by providing just the right amount of information (and the right type) so they don’t have to skim. They find the right content and dive right in. And the benefits don’t stop there. Once you’re writing topics, because they’re small and self contained, you can single source those topics to your heart’s (and wallet’s) content. This means savings during content creation and during translation.
  • Organize your content: Written correctly, each topic satisfies a business use case. That means the user’s reason for looking at the documentation is satisfied every time. And if you think user satisfaction with documentation doesn’t directly impact their satisfaction with the product and the company, then you’re deluding yourself.

And if you’re using DITA, you can use attributes to take single sourcing to the maximum, sharing topics between output types, products, and even departments. Want to hide those graphics for the online help but keep them for the PDF? Easy. Want to hide that first step that only beginner users need? No problem. Want marketing to use just the paragraphs and lists they need? Really simple. All it takes is a little preparation, a little testing, and then a quick option on publish. It’s not hard. It’s not even complicated.

Single sourcing. High usability. Clean, organized content. Your users will love you. Your manager will be amazed that you saved both money and time, and all while meeting or exceeding user expectations.

Is there a downside to writing topics? Well, yes, frankly, there is.

Instead of a dozen files per deliverable, you’ll have ten dozen files (even with wild amounts of single sourcing). If you’re using a regular file folder way of organizing your topics, then it’s going to become cumbersome and you’re going to cut down on your ability to re-use topics between different writers and groups. Plan for a way to organize topics that will let you maximize sharing. Many companies decide to start using a CMS, another cost on the highway to progress.

And don’t forget that writing topics is a change, a big change, in the way you research, plan, and write your topics.  And change can be hard to implement.

But if you think the benefits outweigh the difficulties, like we do, then maybe it’s time to get started.