5 min read

The Art of Topic-Based Writing: How to Craft Compelling Content

The Art of Topic-Based Writing: How to Craft Compelling Content

Imagine your latest piece of writing featured in the New York Times, with a rave review praising it as sensible, understandable, logical, resonating, compelling, engaging, and topical. What writer wouldn't love that? 

But crafting content that genuinely works for your readers, especially when tackling complex technical subjects, requires more than just raw talent or a way with words. It demands careful thought and meticulous planning to structure it in a way that's both relevant and usable for the reader while also being practical and reusable for your organization. 

This is where the art of topic-based writing comes in.

Let’s get into it.  

What is Topic-Based Writing?

Topic-based writing refers to chunking content into concise, self-contained topics rather than sprawling chapters or monolithic documents. As the DITA Wiki Knowledge Base notes, "Topic-based authoring has been a mainstay of technical information development since we first began developing help systems." 

In an era where help content must cover an ever-expanding range of products and be consumable across various devices, well-structured, topic-based writing has become more crucial than ever.

The Chain Analogy

The clearest analogy to explain topic-based writing is that of links in a chain. Imagine each topic as a sturdy link. While each individual link strengthens the overall chain, it could also be swapped out for another equally valid and robust link if needed. The links connect to form a strong whole, yet each one maintains a degree of independence. 

However, online content shatters the limitations of a physical chain, where each link can only join two others. In the digital realm, every topic sits just a click away from any other, allowing this chain analogy to expand into an interconnected web of chain-link fences.

Building the Chain, Link by Link 

Each link or topic serves as a compact, easily digestible nugget of information, complete in itself. It might answer a "what," "how," or "why" question. How do I accomplish X task? What does Y term mean? Where can I locate more details about XY process? 

However, there are more effective transitions to topic-based authoring than hacking a narrative-based chapter into separate topics. Consider the wealth of connective tissue and assumed context woven through a typical book chapter.

Crudely separating that into discrete topics renders the content choppy and disjointed, like scattering the links of a chain into a messy, unconnectable heap. The inherent sense of flow and structure that guides a reader through a well-crafted chapter disintegrates.

Topic-based writing presumes that users might access the topics in any sequence, possibly skipping around as they hunt for specific information. They can grasp any link in the chain or fence, assured that each self-contained topic will deliver value while still connecting to the greater whole.

The Power of Minimalism and Task-Based Content

To elevate your topic-based writing even further, marry it with the principles of minimalism in your task-based content. 

Minimalism involves rigorously editing content to the exact information required (and no more) for the user to complete their task or grasp the concept at hand—delivering the right information when needed. For instance, if a particular step frequently triggers a user error, weave the relevant troubleshooting guidance directly after that step. Or, if a button or component proves hard to locate, provide a clarifying graphic. 

Successfully applying minimalism demands deep product knowledge, frequent user feedback, and a ruthless willingness to prune all non-essential content. The goal is to equip users with streamlined, eminently usable content that empowers them to achieve their objectives quickly and get on with their day. 

Minimalism also means documenting the single best method for accomplishing something, not deluging users with every possible approach. Paring away the extraneous leaves only the most potent and purposeful content behind. Users can then navigate fewer topics but encounter much more information. They'll thank you for respecting their time with concision and clarity.

The flip side of this coin is task-based writing, which recognizes that the heart of your content lies in the procedural. It starts by identifying the users' goals, then crafts lean topics around the tasks required to reach them.

Explanations and reference material not directly essential to completing those tasks can be omitted. The laser focus stays on understanding and facilitating what the user aims to achieve with your product. Minimalism and task-oriented writing work in lockstep.  

Keeping the User's Goal as Your True North

At its core, topic-based writing aims to produce clear, eminently usable content that satisfies your users' needs. "How do I get started?" "What critical facts do I need to know?" Each well-crafted topic swiftly and thoroughly answers those burning questions without sending the user on a wild goose chase for supplementary information scattered elsewhere. Every topic is carefully targeted to address a particular need with precision.

When each topic is skillfully written, users can rapidly pinpoint the knowledge they seek. The information they uncover directly and fully meets their requirements, allowing them to quickly read or scan the topic, find their answer, and move on. The result? Users who are genuinely delighted with their content experience.

The Three Musketeers of Topic-Based Writing: Tasks, Concepts, and References

Within the topic-based writing framework, three primary content types emerge, each playing a distinct role in meeting users' diverse information needs. While the content differs, all three topic types share a common backbone: a title and a body.

Tasks

These topics illuminate the path to achieving user goals, serving as a roadmap of detailed steps to execute each task. They typically encompass prerequisites or post-requisites, contextual information about the goal or task, decision points, and expected outcomes.  

Concepts

These topics shed light on how things work or what they mean. They provide the contextual glue that helps users understand how the pieces fit together into a cohesive whole. Concept topics frequently feature explanatory graphics or illustrations, such as high-level architectural diagrams. (Glossary definitions function as a specialized sub-type of concept topic.)

References

These topics act as quick-lookup repositories for granular, detail-rich information. They often include highly technical graphics, well-organized lists (frequently alphabetical), and/or intricate tables. Users scan—not read—reference topics to rapidly locate a specific piece of information. A specifications table or a command and options list would be prime examples.

Now, if your user analysis determines that all three are necessary, let's examine how you might approach the same subject matter through the lens of each topic type. 

Example Subject Matter: Supported File Types

Let’s check out an example together.

Reference Topic

Provide an alphabetized list of all supported file type extensions and names and their corresponding support levels.  

Task Topics

These would include:

  • Converting Between File Types: Walk the user through converting content from one file type to another.
  • Importing Specific File Types: Show users how to bring various supported file types into the system.  
  • Printing to Different File Types: Explain the steps for outputting content to a particular file type via printing.
  • Exporting Content to Specific File Types: Demonstrate how to save or export system content into supported file types.

Concept Topics

Concept topics include:

  • File Type Storage in the System: Offer a high-level technical explanation of how the system handles and stores different file types under the hood.  
  • Pros and Cons of File Type Usage: This section highlights the key benefits, tradeoffs, and limitations associated with using certain file types in particular scenarios.
  • Implications of File Type Conversions: Discuss the potential downstream effects and considerations around converting between file types.

As you can see, the subject matter dictates the quantity and variety of topics required for comprehensive coverage. Let the content's intrinsic nature be your guide.

Crafting content that resonates with readers and serves your organization well is both an art and a science. By embracing the practice and principles of topic-based writing—breaking complex subjects into crisp, focused, interconnected topics—you'll find yourself well on the way to producing the kinds of compelling content you've always aspired to create. 

Here's to forging stronger chains, one powerful link at a time.

The 7 Cs of Technical Writing

The 7 Cs of Technical Writing

Key Takeaways:

Read More
Internationalizing Technical Content

Internationalizing Technical Content

With the increasing globalization of businesses, internationalizing technical content has become crucial for organizations that need to cater to...

Read More
Technology Marketing Campaigns: A Manifesto for the Modern Marketer

Technology Marketing Campaigns: A Manifesto for the Modern Marketer

If technology is the engine of innovation, consider technology marketing campaigns the grease that turns the wheels. It’s like the game of chess:...

Read More