What is ‘Topic-based Documentation’?

Topic-based documentation, also known as modular writing or authoring, is a flexible approach to content creation that structures stand-alone pieces of content around specific topics. This modular approach allows for content to be easily restructured and reused in different contexts, making it a popular choice for technical writing.

In contrast to book-oriented or narrative content, which is typically written in a linear structure, topic-based writing is focused on creating discrete pieces of content that can stand alone and be reused across different platforms and formats.

What is a Topic?

A topic is a discrete piece of content that is about a specific subject, serves an identifiable purpose, and can stand alone. Topics are also reusable, allowing organizations to ensure a wider reuse of technical information through topic-based writing.

Stand-Alone Topics

A stand-alone topic is constructed in a way that does not need to be presented in context for the target audience to make sense of the content. Once constructed properly, the topic can be reused in any context where it is needed.

Types of Topics

There are four types of topics in topic-based documentation:

1. Procedure: A procedure topic is intended for instructions that describe how to accomplish a task. It lists a series of steps that the user follows to produce an intended outcome.
2. Description: A description topic is intended for information that is objective and is used to explain concepts, definitions, and overviews.
3. Reference: A reference topic is intended for developing reference information, such as component and function lists or technical data.
4. Example: An example topic is used to explain the features and working principles of products, and enhance user understanding on how to utilize the features.

Procedure Topics

Procedure topics are used for step-by-step instructions and are targeted towards personnel with minimal experience who need directions to perform a task. The structure of the overall procedure should be split into logical steps, and each step should contain only one instruction. If the procedure is lengthy, it should be divided into separate sub-procedures, which can also be treated as individual topics.

The level of detail in procedure topics needs to be detailed enough to ensure that even personnel with no experience can successfully perform the procedure. Illustrations should always be self-contained, containing all necessary information required to perform the procedure. Any issues that need clarification in the text should be depicted with an information symbol. The text written with the instructional images should clarify issues that cannot be correctly depicted in the illustration, for example how fast a procedure should be performed or how firm a grip should be used. It is recommended that article numbers are not included in the text, but only in the illustration.

Description Topics

Description topics are used for descriptive text about systems, components, application areas, and similar topics. The descriptive text is used to explain or define a certain topic, and preferably contains both images and text as aids for clarifying the topic. The logical principles such as chronological order, alphabetical or top-down order can be used to structure the topic and help the user in understanding the concept.

The level of detail in description topics depends on the topic and the defined need of detailed information.

Reference Topics

Reference topics are used for developing reference information, such as component and function lists or technical data. The information is typically presented in a table format and provides data and metadata level detail. Users can refer to the topic for further information on specific components or functions.

Example Topics

Example topics are used to explain the features and working principles of products, and enhance user understanding on how to utilize the features. They are a great way to show how to use the products and enhance user understanding on how they can utilize the features.

Conclusion

In summary, topic-based documentation is a modular approach to content creation that structures stand-alone pieces of content around specific topics. By structuring content around discrete stand-alone topics, writers can create content that is reusable and can be presented in different contexts. There are four types of topics, including procedure, description, reference, and example, each with their own unique purpose and structure. When creating topic-based documentation, it’s important to keep the target audience in mind and create content that is detailed enough to ensure even those with minimal experience can successfully perform the task. By following these guidelines, organizations can create technical content that is not only informative but also user-friendly and easy to navigate.