April 9, 2012

The 3 Primary Concepts of Modular Documentation

Kurt Ament authored a book titled Single Sourcing: Building Modular Documentation in which he clearly explains how technical communicators can develop standalone, topic-based information modules that act as the building blocks for a robust set of documentation based on the individual building blocks. This is currently a very popular approach to technical documentation and much has been written about this approach by others since the publishing of Ament’s book.

I’m big on basics. I like breaking things down to the most elemental ideas or concepts in order to fully understand the details that surround them. When it comes to modular (topic-based) documentation, here are what appear to be the three key concepts:

  1. Separate (chunk) information into standalone topics. Most technical communicators who follow this process use three common content types: concept, task and reference. The goal is to create chunks of information that separately contain descriptive information (concepts), task-oriented information (tasks), and reference material the user can look to for more detailed or related information.
  2. Use topic titles that clearly represent the topic’s contents. No two titles should be the same in order to ensure no confusion. These highly descriptive titles should be easily “scannable” so they can act as visual cues to direct users to the specific information they need with minimal hunting around the documentation. Unique and descriptive titles also facilitate better searching.
  3. Link it all together in logical ways. Link related topics together in a way that allows the user to easily jump around the topics with little need to perform further searches.

There is a lot more to creating modular documentation, but if you understand these three basic ideas, the rest of the details will fall into place easily.

For more information, visit these sites:

Editing Modular Documentation: Some Best Practices

Challenges and Advantages of Modular Documentation

Modular Documentation: Bringing the Pieces Together

One Comment on “The 3 Primary Concepts of Modular Documentation

[…] MORE Share this:Like this:LikeBe the first to like this post. […]

Leave a Reply

Your email address will not be published. Required fields are marked *