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.
Now THAT's an interesting question you posed on techwr-l. I would be very interested in the summary if you can provide one. On-list reaction has not been overwhelming, unfortunately.
Companies come to regard information as a commodity that is part of the product lifecycle. In order to be able to link the "information production process" with product development and production, content has to be organized in a way to be linkable to product structures. This is not to say that the structure (TOC) of a manual has to represent the exact product structure, but you have to able to identify all relevant content for a given product module. That being accomplished, you can derive customer-specific or configuration-specific documentation form ordering data out of an ERP or PDM database. So, mudularization begins with identifying information-relevant product modules.
The second step is the definition of content modules. A module has to meet the following criteria:
- defined target audience (is the content directed at end users, maintenance personnel, ...?)
- self-contained (key to reuse; no textual cross-references to other modules, usable in different contexts)
- media-neutral (what if you want to use it on your web page next week, not only in printed matter?)
Of course, you have to use a tool that enables you to work with modules and produce meaningful output at the same time. For example, cross-referencing is an integral part of every documentation product. Working with modules, however, requires a tool that handles references for you, checking if the reference target is present and leaving the reference out if it isn't. To make a long story short, in order to justify the money and effort that goes into tools and procedures necessary, you have to have the need for reuse and single source publishing.
To answer the questions in detail:
1) Yes, we write modular documentation, because we need to be able to provide customers with tailored documentation for their individual machinery. We have to be able to do that with as little additional work as possible. Furthermore, translations are a big issue. We want to be able to exclude modules that have already been translated from having them translated again. This saves us more than half of our translation budget. And we want to create audience-specific documents at the push of a button.
2) Modules are only insufficiently decribed if compared to "chapters" or other elements of linear print documents. If you have to make a comparison, in print output they are subchapters in our case. They vary in lenght from half a page to about five pages. Smaller chunks ("atomized documents") are unsually not reusable in an efficient way.
3) Yes, reuse is the only justification for modularization. At the end of the day it all boils down to doing more (document types, output formats) for less (money). If your information pool and product structure allow you to reuse content, quickly finding and reusing the relevant modules is the key to saving time and money.
Best regards,
Armin Hoffmann.
Eric J. Ray asked:
* 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?
NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
?Mustang? (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
