Mark Seymour - Reference and Resources

Login FormClose

Modular Documentation

Modular documentation is a method of building documents from blocks of information that have a standard information type (such as procedure, concept or reference) and/or standard content type (such as upgrade procedure, network diagram or server specification).

You see these blocks of information in all technical documents, but do they appear consistent in structure and location across a document set? If they do, they have probably been planned using a modular documentation method.

Building documents from modules provides significant benefits to the information designer, documentation manager and end-user, including:

  • Single-sourcing and reuse - use the same module in numerous documents or document sets (such as for different versions of an application), removing the need to update information in each document separately
  • If modules can be used in different documents, they must be of similar structure, format and writing style, all of which promote consistency and clarity to the end user
  • Modular documentation forces the information designer to properly analyse and plan a document set before starting any writing
  • Modular documentation is normally built in a tool capable of using structured languages such as XML. These tools (FrameMaker, Epic, AuthorIT, etc.) can publish to multiple output formats such as HTML, XHTML, PDF, Word or HTML Help.

Modular documentation employs an information type architecture to define the standard templates for modules. A common information type architecture is DITA (Darwin Information Type Architecture), originally developed by IBM. DITA has three standard information types (task, concept and reference) and a DITA map to pull them together into a document structure.

Modular documentation is recorded in a content specification (similar to the DITA map mentioned above). In mature industries or companies, the content specifications may be standardised as part of an operator model (such as the Telecom Operator Model, TOM) or framework (such as the Microsoft Operations Framework, MOF). In simple terms, these provide the table of contents (TOC) for standard documents such as installation guides or functional specifications.