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.
2 Comments