TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> I'm looking for a consensus, of sorts, about what
> technical writers mean by the term "modular documentation".
There seem to me to be two fundamentally opposed and commonly confused uses
of the term "modular documentation", as well as a third use that is not
common, but may provide the key to resolving the conflict between the first
two.
The first type is what we might call user-centric modularity. User-centric
modularity starts with the proposition that readers of technical information
are best served by small tightly focused pieces of information that contain
everything they require to do one task. These are variously called
topics, modules, and information maps.
The second type is what we might call management-centric modularity.
Management-centric modularity seeks to make the management of a
documentation project easier by writing information in small chunks rather
than large documents. Writing information in small chunks make managing a
documentation project easier in several ways. It makes it easier to share
authoring between different writers. It makes it easier to track progress.
And it makes it possible to reuse modules in different books, reducing
workload.
Unfortunately, there is a seldom acknowledged tension between user-centric
and management-centric modularity. User-centric modularity seeks to present
the user everything they need to do a particular task in a single module.
This means that certain types of information that are common to many tasks
will be repeated many times over in many different modules.
Management-centric modularity, on the other hand, seeks to eliminate
duplication of information. It stresses an approach to module design that
seeks to eliminate redundancy of information between modules.
People who adopt modular writing approaches in the hopes of achieving reuse
and single sourcing are often disappointed to find that they achieve almost
no significant reuse in real life. But this is not surprising if they have
taken their approach to modular writing from a user-centric modularity
source such as information mapping. User-centric modularity is the very
opposite of the kind of modularity that makes for ease of single sourcing
and reuse. User-centric modules are highly specific to one individual task
of one individual user, and therefore not likely to be highly reusable. And
because they require all relevant information to be inline in the module,
they introduce a high degree of redundancy across your information set,
which is the very opposite of what you trying to achieve with single
sourcing.
People who adopt management-oriented modularity, on the other hand, often
have trouble producing user friendly information products. Because reusable
modules have to be made highly generic, they do not fit user's tasks well.
And because information is not duplicated inline, information products have
to rely heavily on cross references, meaning that users have to jump about
through the information set to find the information they need.
The third type of modularity, which, for sake of uniformity, I will call
subject-oriented modularity involves organizing information around the
subject matter described. Information is gathered into subject oriented
modules, and each type of information about a subject is structured and
labeled carefully so that the appropriate pieces can be selected and ordered
to synthesize user-oriented modules for presentation.
This approach has many advantages.
* It provides for the highest level of single sourcing
* It provides for the easiest management of change, because all the
information on a particular subject is kept together in one place
* It allows for the creation of highly user-centric modules, without having
to worry at all about limiting the amount of redundancy that is created
between individual modules
However, it also requires a higher level of abstraction in information
design and a higher degree of sophistication in document synthesis.
---
Mark Baker
Stilo Corporation
1900 City Park Drive, Suite 504 , Ottawa, Ontario, Canada, K1J 1A3
Phone: 613-745-4242, Fax: 613-745-5560
Email mbaker -at- ca -dot- stilo -dot- com
Web: http://www.stilo.com
This message, including any attachments, is for the sole use of the
intended recipient and may contain confidential and privileged
information. Any unauthorized review, use, disclosure, copying, or
distribution is strictly prohibited. If you are not the intended
recipient please contact the sender by reply email and destroy
all copies of the original message and any attachments.
