Modular documentation: How to make both writers and users happy

Learn about a new approach to modular documentation based on user stories, and how it can make life easier for writers and improve user experience.
501 readers like this.
Typewriter keys

Original photo by mshipp. Modified by Rikki Endsley. CC BY-SA 2.0.

Modular documentation is not a new concept. Writing documentation in modules that can be combined and reused has been around, in various incarnations, for many years, and it has many proponents as well as detractors. This article introduces a lightweight approach to documentation modularity. The idea is rooted in improving content by giving it a better focus through user stories. (See Documentation based on user stories for a discussion on how user story-based documentation compares with feature-based docs.)

DITA and friends

Let me emphasize right from the start: This is not DITA (Document Information Typing Architecture), nor has the approach been inspired by DITA. The focus is on user story-based documentation, and its modular structure is a means to an end—simplifying authoring, ensuring consistency, and streamlining documentation processes.

How modularity helps writers

To make writing user story-based documentation as simple as possible, we have come up with a number of best practices. Among them was writing standardized modules and combining them together. Structuring docs in a modular manner and using templates for a few fundamental content types provides several advantages:

  • encourages consistency
  • enables reuse of chunks of content
  • makes the proposition of contributing to documentation much less daunting for new colleagues

By storing the documentation sources in modules, we aim to improve the way documentation is presented to users.

Templates for modules and assemblies

The main unit of content and the most basic element of our modular structure is a module. By combining modules, a writer can construct a user story in a component called an assembly. We have defined the following three types of modules:

  • Procedure
  • Concept
  • Reference

An intuitive template has been developed for each of the module types and for assemblies. The templates provide guidance regarding structure, style, and suitable content. These templates are in the Modular Documentation Project source repository on GitHub. The repository also has a concise manual that explains how to use the templates, including examples of real-world docs formatted as modules.

Consistency and content reuse

From a writer's perspective, using predefined templates for modular units of content:

  • encourages brevity and consistency, and
  • makes it easier to focus on the content itself while eliminating the overhead of formatting and structuring.

A writer's expertise is still required to ensure technical accuracy and a proper tone and voice.

Collaboration between several writers is less painful when they follow the template structure. Not only can writers easily pick up work where others have left it when a consistent format is adopted, but individual modules can also be readily reused in multiple assemblies.

How modularity helps readers

Modular documentation also has the potential to significantly modernize the user's experience. The user can be offered a dynamic, customizable experience that provides many new ways of accessing and consuming documentation.

Keep the books and add user stories

Guides, books, and manuals all offer advantages for presenting documentation based on features. These formats are well-suited for comprehensive sets of content that seek to provide details about all there is to know about a particular product. The format invites users to read from start to finish.

Modular documentation, however, suggests other forms of presentation. In addition to forming large guides from sections and chapters, a modular structure allows more dynamic ways of browsing, selecting, and consuming content. Provided the modules are used as building blocks for user-story assemblies, the individual user stories can be shown independently.

Customize books based on need

Careful use of metadata allows users to filter the entire body of available content into custom sets of modules and assemblies. This gives the user the opportunity to select only the documentation that pertains to their particular area of interest or even build their own guides.

A more straightforward, targeted approach

Structuring user story-based documentation into assemblies and modules with the help of predefined templates makes documentation work more straightforward, supports consistency, and allows for efficient content reuse.

Additionally, the modular structure makes it possible to present documentation to users in a manner that better targets their needs, creates a more dynamic experience, and by utilizing metadata, potentially offers customized subsets of docs based on a user's particular needs.

Learn more about modular documentation in Robert Kratky's talk, Going Modular: Turning Legacy Docs into User-Story-Based Content, at Open Source Summit EU, which will be held October 23-26 in Prague.

Do you have an article idea? Submit your story proposal to open@opensource.com.

Robert Kratky
Robert is a long-time Linux user and fan of open source. In the role of a technical writer at Red Hat, Robert specializes in developer docs and improvement of user experience with documentation.

2 Comments

Nice work. Glad to see we are at least two promoting documentation and modularity ;) Documentation needs also, like code, updates in sync with other components and therefore versioning.

The same principles should apply to code documentation: comments. I see most projects, open source, with no comments at all.

Unfortunately, documentation has been considered the fifth wheel in most projects over the last 30 years because of $$$.

Speaking as someone who has worked quite a bit on documentation, I would like to see a drift away from what feels like socially-acceptable trolling about the absence of documentation. Often, those who complain about the inadequacy of documentation are those who never contribute to some project. If you know what good documentation looks like, you should be able to contribute to make it better.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.