Getting Started with Topic-Based Writing

Think for a minute about how you would like to see your writing described by a critic (say for the New York Times): sensible, understandable, logical, resonating, compelling, interesting…topical? Writing content that works for your readers, especially when it covers something technical and complex, doesn’t just happen. It takes some thought and planning to structure it, both to be usable and relevant to the reader, and to be reusable and effective for your organization. Enter: Topic-based writing.

Topic-based writing refers to the method of writing content so that it’s chunked into short topics instead of longer chapters or documents. The DITA Wiki Knowledge Base explains that the “Topic-based authoring has been a mainstay of technical information development since we first began developing help systems.” And as help expands to cover a wider range of products to be consumed on one or more of a vast array of devices, well-structured, topic-based writing becomes ever more important.

The clearest analogy I’ve found to explain topic-based writing that of links in a chain. Each link is a topic. Each link makes the entire chain stronger, but each link could be replaced with another, equally valid, equally strong link. Each link, although connected to other links, does not completely depend on the others. They are connected but they are still independent pieces that make up the stronger, and more versatile, whole.

Unlike the limitations of an actual, physical chain where each link can only connect to two others, content delivered online has no such limitation. Each topic is only a click away from any and all other topics. This means we can expand the analogy to a chain-link fence or even a web of chain-link fences.

We start with an individual link. Each topic is a small, easily consumable nugget of information that is complete in and of itself. Each topic answers the question of what, or how, or why. How do I do x? What is y? Where can I find details about xy?

However, simply chunking your chapter or narrative-based content into separate topics is not an effective way to make the transition to topic-based authoring. Think about how much connective meaning occurs when you write a more narratively structured chapter. Simply separating this content into topics makes it choppy and unusable. Just pull the links apart, and they sit in a useless, unconnectable pile. You cannot see or infer any kind of order or structure as you can with a chapter, where one topic is referring to another as though someone would be reading them in order.

Topic-based writing assumes that the user could read them in any order and may skip around to different topics, as needed. They may pick up a link anywhere in the chain, or anywhere in the fence for that matter, getting the benefit of the self-contained link while staying connected to the whole.

Minimalism and Task-Based Content

For the perfect complement to topic-based writing, apply minimalism to your task-based content.

Minimalism concerns editing down content until you provide exactly the right information (and no more) for the user to perform the task or understand the concept—basically, to get the information they need at the point they need it. For example, if a step often leads to an error for users, then you include troubleshooting information right there, after that step. If a button or bolt is hard to find, you provide a graphic to help identify it.

To apply minimalism successfully, you need to understand the product very well; frequently get feedback from users; and be willing to cut out all non-essential content so that users are left with streamlined, usable content. Help them reach their goal with your product quickly and get on with their day. Minimalism also means that you document the best way to do something not all the ways to do something. By removing all the extra information from the content, you are left with content where each word has value. Users have to wade through fewer topics of higher quality content. They appreciate brevity and clarity.

Task-based writing, the other side of this coin, recognizes that the core of your content is procedural. You identify the users’ goals and write those tasks. Add other information only to support those goals. Omit explanations and reference material not essential to a user performing a goal. Focus on understanding what the user wants to accomplish with your product. Write that content in topics with minimalism applied.

Writing with the User Goal in Mind

Remember, the goal of topic-based writing is clear, usable content written to satisfy users’ needs. “How do I get started?” “What do I need to know?” Each topic answers those questions then and there, without forcing the user to look up other information somewhere else. And each topic is written to be right on target for a specific need.

When every topic is well written, the user can find information quickly and the information they find is exactly the type of information that they need. They can quickly read or even scan the topic, get their answer and be done. The result: Maximum user satisfaction.

Topic Types

Within topic-based writing, you can create three different kinds of content, each of which provides a different type of information for users, satisfying different needs. Topics of all three types include a title and some content.

Tasks: Tell them how to accomplish their goals. It provides detailed steps to perform that task and would include pre- and post-requisites, some context about that goal or task, choices, and/or results.
Concepts: Explain how things work or what things mean. Concepts give them a way to understand how things fit together. Concepts often include graphics that explain or illustrate, such as an architectural diagram with high-level information. (Glossary terms are a sub-type of a concept topic).
References: Quick look up information with lots of detail. These might include very technical graphics, organized lists (often alphabetical), and/or very detailed tables. Reference topics are meant for scanning, not reading. Example: A specifications table or a command and command options list.

You could cover the same subject matter with instances of the three different topic types (if your user analysis shows that each is essential).

Example for subject matter: Supported file types.

Reference topic: An alphabetical list of all supported file type extensions, names, and the level of support.

Task topics: