Five Easy Ways to Improve Your Docs: Part 2, Break Boulders into Pebbles

As a software product develops, so too does its documentation. In one recent project I worked with an online wiki that contained over 200 topics that was growing at a rate of around 15% per bi-annual release. If you assume that your company is going to grow and your product offering will become more diverse and complex, it won’t be long until you are looking at hundreds of print pages spread across some smaller number of web pages. And at the point when you have 300 - 400 topics in the system, you have to think about the very important question of how you, or anyone else, will be able to find what you’re looking for in that haystack, whether for informational purposes or for knowing what you have to add and update for the next release.

The good news is that if you’ve taken a topic-based approach to your documentation, where one topic corresponds roughly to one concept, task, or reference topic, as in the DITA model, you’re probably okay. That’s because you can search for information on a granular level, and target specific topics or subject areas for updates. At the same time, having one topic for a specific task, for example, enables you to refer to it from other tasks when necessary, rather than having to repeat the same information (and potentially have it disagree in multiple locations). When your support or engineering colleagues, or your customers, search the documentation they’ll be able to easily identify the information they want, and it will be a small task to incorporate it into your support organization's ticketing and customer response systems.

Unfortunately, there are many examples of documentation that work from the concept of documentation as book, with chapters and sections, even in online documentation. These tend to evolve into long scrolling pages that are added to over each release, or which become catch-alls for everything related to one specific topic. Instead of granular chunks of information, with distinct titles that tell you what they contain, these are nearly impenetrable walls of text that impact the usability of the docs in two significant ways.

The first is that there is no way to have an overview of the doc content. When I look at the navigation tree for online product documentation, I should have a pretty clear of the major conceptual domains of the product, and the tasks associated with them. I should also be able to browse that tree to understand how the tasks fit into complex processes, how they relate to one another, and the conceptual and reference information necessary to complete them. If all this is presented as sections and sub-sections in a single topic for one process, even one with a linked table of contents at the top, it presents a substantial challenge for being able to gain a structured understanding of the process and then browse through individual tasks.

Second, because so much information is aggregated into every boulder of text, it becomes extremely difficult to search for specific information. If you are looking for something related to a process, with only a single chapter on that process as main information container, then you are left to tab through multiple Find in Page hits on terms, and long scrolls, to find the right reference. This is assuming that what you’re looking for is mentioned in only one chapter; woe unto you if your keyword phrase finds its way across multiple pages. That’s bad enough for your users, but keep in mind that when it comes time to update the docs for a release, you’ll likely find yourself relying on tribal lore of “that’s on page 321, second paragraph” to figure out exactly what needs to be changed.

Taking a topic-based approach to documentation if you’ve been thinking in terms of chapters, and have been taking an additive approach to them over multiple releases, is not exactly that easy, and I have certainly spent many weeks working on such projects. It is very much akin to to taking a very heavy hammer to a large boulder with the intention of reducing it to gravel. However, the payoff in information findability, and a much smoother path to documentation release management, is more than worth it. This article on getting started with topic-based writing from TechWhirl, the website arm of the Tech Writer email list, has great tips on how to get started, and links to more resources.