Modular Docs Part 1: Why You Want Modular, Topic-Oriented Documentation
By Eric Armstrong on Oct 06, 2008
This writeup provides a list of motivations for modular, topic-oriented
- User Focus:
- Modular Authoring
- Reusable (saves time)
- Contextually Variable (minimizes work)
- Modular Delivery
- Dynamically Deliverable
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
focused--the razor with which everything irrelevant is ignored. The
is minimal documentation that focuses on the user's needs.
A component tends to be tightly focused on a specific
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
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.
Reusable (saves time)
The ability to use topics written by others saves time when creating
That reuse will typically occur within a department, but it can also
departments, and even across organizations--given a common standard for
document formats, which allows information to be interchanged. (Of
further the information travels from home, the more imperative for
content to be
separated from presentation, since the presentation format will
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
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.
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
appearance and structure. That regularity helps a user anticipate
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.
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.