Modular Docs Part 1: Why You Want Modular, Topic-Oriented Documentation

This is the first in a two-part series. Part 1 describes the motivations for modular documentation. Part 2 zeros in on the reasons for choosing DITA.

This writeup provides a list of motivations for modular, topic-oriented documentation.


  • User Focus:
    • Applicable
    • Comprehensible
  • Modular Authoring
    • Reusable (saves time)
    • Contextually Variable (minimizes work)
  • Modular Delivery 
    • Readable
    • Regular
    • Findable
    • Dynamically Deliverable

User Focus


Topic-oriented information starts with the user--with an analysis of the tasks they need to perform. Only the conceptual and reference information necessary to carry out those tasks is added. Everything else is treated as unnecessary.

With that approach, "user focus" becomes the prism through which documentation is focused--the razor with which everything irrelevant is ignored. The result is minimal documentation that focuses on the user's needs.


A component tends to be tightly focused on a specific concept, task, or bit of reference material. That limitation keeps it short and easy to digest:

  • Conceptual material stands alone, effectively acting as a semantic glossary for the user, enabling them to grasp the system ontology.

  • Tasks are short series of instructions that are easily followed. The absence of conceptual and reference material keeps them at a high enough level that the user can see the procedural forest (collection of steps) rather than having a view that is limited to the trees (individual steps--when each is a page long, the user forgets what they were originally doing by page 9.)

  • Reference material likewise contains little to read. The user can rapidly access any material they need to vary an existing task or carry out a new one.

Topic types tend to enforce the boundaries, in much the same way that an object-oriented language constrains development to an object-oriented design, although they are not, strictly speaking, necessary.

Modular Authoring

Reusable (saves time)

The ability to use topics written by others saves time when creating new works. That reuse will typically occur within a department, but it can also occur across departments, and even across organizations--given a common standard for document formats, which allows information to be interchanged. (Of course, the further the information travels from home, the more imperative for content to be separated from presentation, since the presentation format will undoubtedly differ in other departments and organizations.)

But note that there is a big difference between document components that can be reused, with a little work, as compared to components that are truly and simply reusable as they are. Modular components that already exist as independent entities are like Lego blocks. You can use one to create to an airplane or a boat. It makes no difference. Other information structures are more akin to model airplanes--the components could be reused, but only after you do the surgery necessary to extract them from their current setting. The degree to which additional effort is required is the degree to which reuse is impeded.

For more on those differences, see Modular Docs Part 2: DITA vs. DocBook.

Contextually Variable (minimizes work)

The ability to add variations to an existing topic makes it possible to reuse existing topics with minimal change--and without fear of creating dual-source documents whose contents will tend diverge over time.

Contextual variations can be constructed either with conditionals, where you add metadata information to elements so you can filter out items that don't belong in a particular context. (Unix path vs. Windows path, for example.) It can also be done with composition, where you create a variable that contains the path, and substitute different values at production time. Both capabilities are useful, for different purposes.

Modular Delivery


Topics naturally lend themselves to delivery as individual HTML pages. Since each topic is tightly focused, the material is presented without distractions, once the user navigates to the page they need, whether by navigating, searching, or following a link.


Because they stem from shared information templates, and because they go through common production procedures, delivered topics tend to be more regular in appearance and structure. That regularity helps a user anticipate where information will be found, and helps them skim for information more easily.


Users can more easily find the information they need, searching based on topic type or metadata that applies to the topic. For example: "All tasks pertaining to Solaris administration".

Modular topics also allow for aspect-oriented browsing, where the user gets a lists of all Solaris topics, for example, and then reduces that lists to the tasks they can perform. Or they might start with a list of tasks, and then filter out all but the ones that pertain to Solaris. (With true aspect-oriented browsing, the user can start with whatever information they have, and eventually drill down to the information they need, adding more filtering criteria as they learn more.)

Lists of related links also help users find things that are relevant, as are "advertising" mechanisms that direct users to things that others have found useful.

Dynamically Deliverable

When documents are built from components, and the components can have contextual variations, it becomes possible to construct built-to-order documents "on the fly", in response to user demands, rather than having to pre-create static versions of all possible variations. Once such a system is in place, it becomes possible for users to further customize the results by modifying the list of selected topics, rearranging their order, or even by adding new topics.

Next: Modular Docs Part 2: DITA vs. DocBook


Post a Comment:
  • HTML Syntax: NOT allowed

« August 2016