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.
* Do you currently write "modular documentation"? Why
or why not?
* What _is_ modular documentation? (Please provide
examples or an adequate description for what your
modules look like. Are they paragraphs? Chapters?
Tasks? How do you tell a new writer what to create?)
* Do you reuse/repurpose documentation modules? Why or
why not?
To take the second question first, I see modules at two levels. The
lowest level is individual topics. The topic might be a complete
procedure, a dialog description, or a chunk of conceptual information.
These chunks, which we term "Content Items", are the basis of the
enterprise content management system my company produces. In addition to
the chunks of text, associated graphics and other binaries are managed
separately as unique Content Items, and associated with the text content
in a process we call "assembly". Another tool I've used, Author-IT, works
in a similar manner. Using the paradigm of object-oriented programming,
it considers a document ("book object") to be a collection of
"documentation objects" such as topics, files/graphics, hypertext links,
etc. In both cases, the unique chunks are aggregated to create the final
output, be it a web page, a .pdf or Word document, or online Help.
I see a second level of modularity as intermediate between these discrete
chunks and the complete document. For example, you might have a
collection of topics addressing a single issue, such as a portion of
product funcationality. You might use most of this information both
online and in print. You could consider such a collection to be a
"module". Which addresses your third qestions, because we use both
individual topics and collections of topics both online and in print, and
often in multiple documents addressed at different audiences. For
example, I have a security module that I use in three different documents:
two are printed and targeted at different audiences, one is online for the
software tool that is used to manage security. It's the same information,
it's just accessed in different ways.
Modular documentation is thus closely related to single-sourcing. In
fact, that's why we use both levels of modularity. We have different
audiences using the same information in different contexts. Rather than
maintain multiple instances of the same information, we maintain a single
instance and deliver it to different outputs. This approach both
accelerates the initial development process and reduces the amount of time
we need to devote to maintenance.
Hope these ideas are helpful.
Bob Johnson
Documentation Specialist
Percussion Software
Stoneham, MA
