Modular Docs Part 1: Why You Want Modular, Topic-Oriented Documentation
This writeup provides a list of motivations for modular, topic-oriented
documentation.
Contents
- User Focus:
- Applicable
- Comprehensible
- Modular Authoring
- Reusable (saves time)
- Contextually Variable (minimizes work)
- Modular Delivery
- Readable
- Regular
- Findable
- Dynamically Deliverable
User Focus
Applicable
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.
Comprehensible
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.
Note:
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.
Note:
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
Readable
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.
Regular
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.
Findable
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.
