Topic-based authoring for knowledge bases

Topic-based authoring is a modular approach to content creation focusing on documenting particular tasks, and it’s particularly suited to software products.

This is because our help bases are online and providing singular, topic-based articles helps customers to use our software better.

DITA’s (Darwin Information Typing Architecture) online help community says:

“Authoring in topics provides information developers with a way to create distinct modules of information that can stand alone for users.”

Where topic-based authoring came from

Topic-based authoring arose in response to the death of the traditional user manual. In these user manuals, usually printed, content topics would be dealt with in a narrative order decided by the documentation writers.

There was an expectation it should be read beginning to end and little attention was paid to the actual usage patterns of the users.

With a move towards modular documentation, this means that technical authoring has increasing focus on flexibility, usability and user experience.

According to DITA, topic-based authoring is related to the minimalist approach:

“The minimalist approach to information design focuses on identifying the smallest amount of instruction that allows for the successful completion of a task, or that provides basic knowledge of a concept.”

In other words, topic-based authoring is practical and pared down.

An evolution of documentation

This contrasts the days when help manuals used to be deadly long, and contain everything anyone might want to know about a product. A user would have to rely on the table of contents or index to try to find the information they needed.

The manual might be organized from A-Z, or take you through an expected ‘procedure’. You would have to guess what features might be called.

In the days of print, there was no CTRL + F, so documentation wasn’t particularly easy to use. If you had a problem, you had to call tech support, and probably wait on hold.

“You'd need the patience of a dead owl to get through some [user manuals],” says well-known technical writer and blogger Tom Johnson, when discussing topic-based authoring.

With the spread of Software as a Service (software delivered over the internet on a subscription-based model), there has arisen a need for a more modular approach to documentation and knowledge base management.

Benefits of topic-based authoring

Topic-based authoring suits our multi-platform, content-driven digital environment.

The ability to search quickly, and easily click through to other content, now makes topic-based authoring possible and preferable.

As SaaS is constantly evolving, this requires a dynamic approach to documentation.

When you add a new feature to your product, you can simply add another topic to your knowledge base - instead of potentially reorganising the whole thing. Or, even worse, not documenting new features at all.

The idea behind topic-based authoring is that it’s more dynamic, and also more cost-effective. You can repurpose content for different formats and reduce time to market by releasing core content modules quickly. If you’re taking your product to international markets you can also translate the content you need the most, further reducing costs.

It’s more user-friendly than documenting every feature, as you only include the content that users need to perform tasks with your product. You scrap everything else.

Downsides of topic-based authoring

A current debate is taking place over how useful topic-based authoring actually is. This in part because of how some companies take modular content to an extreme, producing topic-based content that is not interlinked in any way.

Tom Johnson is somewhat against topic-based authoring, on the basis that it doesn’t fit well with real-life experience. He advocates publishing your knowledge base content as a series of articles that connect together, rather than disparate topics. He makes the comparison with blogging, and publishing blog posts in a series.

Tom’s overall point is that user tasks can be written using a topic-based approach, but not conceptual ideas within a system. Your knowledge base needs to be designed cohesively to ensure your topics are useful to all types of users.

To quote Tom, “The real heart of technical instruction doesn't lie in the step-by-step how to information, the 1-2-3. It lies in understanding concepts and how they work together to produce an end.”

Writers like Tom are taking issue with the DITA approach, the origin of topic-based authoring, because it does not provide a theory of Information Architecture. It only provides a way to write content.

Topics as part of a larger whole

Although your topics should be consumed independently, they must be part of the ecosystem of your knowledge base content. Indeed, technical author Mark Baker agrees. Topic-based authoring is great, along with a healthy dose of information architecture.

Successful topic-based content is linked to a larger whole so all users can make sense of its meaning. This is because not all users understand everything your product can do, so they wouldn’t necessarily think to look for all of your content.

Writing good topic-based content is one thing, but it should be organised coherently so users know where it fits within the context of your product. This requires having oversight of your product, its uses and position within the industry.

To be fully reliant on topic-based authoring also requires a large amount of prior knowledge of your users needs and habits.

Final remarks

As software evolves, so should your knowledge base. It should be flexible and open to change.

Topic-based authoring is related to Just In Time help, and we’ve published another two articles on this subject. Find out more about Just In Time methodology and take a look at our practical guide.

To use topic-based authoring requires a thorough understanding of your users and gathering feedback is essential.

Even though topic-based authoring is very useful, consensus also shows that designing the flow of your information into a coherent whole is still essential, to ensure your content has deeper meaning.

KnowledgeOwl has robust software to support your topic-based authoring goals. Take us for free spin today.