Notes from 48th International STC Conference
Chicago, Illinois, May 13-16, 2001
Authoring in a Single-Source Environment
JoAnn Hackos is an internationally known expert, multiply published author,
and successful entrepreneur in technical communication, particularly electronic
publishing and project management. Her firm is ComTech.
Session Description: This session addressed techniques for effective
reuse of content in multiple deliverables.
- JoAnn began by recounting a story about how she once actually fell asleep while
lecturing a class. "It's really bad when you start boring yourself," she allowed.
She promised not to demonstrate that technique at this session!
- No amount of technology will ever change the core skills of
effective authorship. However, it can make a vast difference in cost-effective
creation and dissemination of deliverable documents.
- The old paradigm: one author, one book. Author had total responsibility for
design, content, format, editing, and publishing.
- After total chaos in the production of her first book,
Your Documentation Projects, Hackos resolved always to maintain total
control of production in all future publications. She now sends an unchangeable
postscript file of final galleys to her publisher so they can't mess up the final
- The dilemma: Although one-book authorship is easy to manage, has lots of
personal satisfaction, provides end-to-end control, and allows personal responsibility,
it also has significant drawbacks: it is difficult to reuse the information, it is
expensive to maintain consistency, it is expensive to translate, and it entails
too many responsibilities.
- Use of synonyms plays hell with translation. Despite repetitiveness, you have
to use one term for one thing or one concept throughout the document.
- Collaborative authoring is a necessity in a single-source environment.
Collaborative authoring allows cost-effective information reuse, specialization
through teamwork, focus on users and content, and consistency and adherence to standards.
- Collaborative authoring demands respect and close cooperation, in order to
develop a composite style that is transparent to the reader.
- Production should not dominate users and content in book planning, authoring,
and publication. It's important, but it is a means to an end, not an end in itself.
- On the flip side of collaborative authoring, it represents a new and different
way of working which demands new skills be learned. Consistency and adherence to
standards and information coherence within components are critical.
- Most organizations tend to fear that a collaborative project will not be done
as well as one that has a single person fully responsible for the entire task.
- A self-managed team will be most effective if it blends a full spectrum of
personalities, but only if there is some degree of parity in competence as well
as an equitable workshare among its members. For example, in a student teaming
project, many of the best students were uncomfortable with teaming, asserting
that they felt the process was holding them back, not helping them.
- Owner manuals for several major auto companies are outsourced to one large
vendor and are single-sourced. 17,000 different manuals came from one
single-sourced database and a process teaming SMEs, editors, and information
architects using established templates and stylistic guidelines. Each manual
is assembled from the same database, tailored to the individual vehicle.
- XML modules of information are the key building blocks in the single-source
- For online reviews, XML files are exported as PDFs.
- Searching for components. Metadata facilitates searching (subject matter details;
information type; author, date, revision, version). Metadata structures the contents
of the repository to facilitate reuse.
- Metadata is similar to indexing... affixing labels that facilitate electronic
access via search engines, etc.
- Searching and reuse. Object-oriented databases are oriented toward rapid retrieval
of information for reuse (versus re-creating the information).
- Reusing components.
- Large grains are easiest to reuse. Whole chapters and sections are reassembled
in many different contexts.
- Smaller grains are more difficult and costly to reuse: e.g., graphics, warnings
and cautions, boilerplate text; concepts, procedures, reference information; steps
in a procedure. Most expensive instance of reuse was a manual for Army howitzers,
which is governed by a spec demanding adherence to complex and exacting requirements.
- "Furthermore, it may be possible for us to add additional metadata tags to the
repository by storing the metadata in an external file. We may also be able to
write a script to change the attribute values."
- Reusing unstructured text is rarely possible. Idiosyncratic writing and styles
- Modular writing eschews transitional expressions like "Furthermore," because
they are inimical with rapid retrieval and reuse. "Furthermore" implies a number
of foregoing points, which are lost if the paragraph is lifted as a stand-alone
chunk of information.
- Searching for isolated snippets of reusable text is unlikely to be productive;
better to seek larger modules of information that can be reused as
is (or with minimal editing).
- Structure authoring enables reuse. Valid XML authoring reinforces rules and
encourages consistency. Standard information types and content units encourage
- Subsections can be named according to their content, improving the possibilities
for reuse down the road. If subsections are to be reused from within the document,
it's important to use XML inside the document. If not, XML might be used only
external to the document; in this case, "wrapping" reusable segments is probably
the best approach.
- Information reuse demands word-for-word accuracy...otherwise, translation is
likely to run into problems. Even subtle differences (e.g., pick up vs pickup)
can wreak havoc in reuse of information.
- Structured authoring can be content-based or format-based. If the editor focuses
totally on format and mechanics, the content becomes secondary and the user is
disserved. On the other hand, if total focus on content causes inconsistencies
in format, information reuse is greatly complicated.
- Structured authoring includes topics, components, and effectivity codes.
- IBM has developed
Information Topic Architecture (DITA).
- Topic: concept, procedure, reference
- Organic structure: customer requirements, business requirements, author requirements.
- Can be found at IBM Web site or via search on DITA...a valuable tool...and free!
- If you give your authors a simple, concrete, easy-to-follow format, you will
be much more successful than if you try to impose a complex set of codes, etc.
- Effectivity codes are metadata descriptors that label variable components
(note that the codes are enclosed in carat brackets):
- Job roles
- One writer becomes a subject-matter expert, handling multiple versions of a product
or other variables, and multiple information types (concepts, procedures, reference)
- Information architect provides output definitions, content specifications,
repository integrity, and release requirements.
- Information designer is another specialist, handling graphic design, Web design, etc.
- Widespread access to the database places strong accountability on authors to
provide accurate information...errors are, in essence, public.
- Component guidelines and standards. A purpose statement provides direction.
- Rather than embed design details in a training tutorial, the tutorial is
hot-linked to information modules within the overall database that provide the
detailed design information.
- Repository management
- Write once
- Use in many contexts
- Label for accurate retrieval
- Emphasize usability
- Focus on minimalism
- Additional resources for content management/structured writing
- http://www.usabledesign.com for workshops
- http://www.comtech-serv.com for white papers,
for Best Practices newsletter, e-Newsletter subscriptions and membership
- Single-source listserv membership
E-Business Workplace: Discovering the Power of Enterprise Portals,
by Matthias Vering, Grant Norris, Peter Barth, and James R. Hurley, deals with
single-sourced internal databases within companies
Portals: Revolutionizing Information Access to Increase
Productivity and Drive the Bottom Line, by Heidi Collins, deals with
development of single-source databases to increase corporate profit margins.
- Hackos will post ROI data on conversion of databases to single-source format
to the STC Web site for the conference.
- The process of converting a large corporfate database to single-source format
takes approximately a year, but the long-term payoff is enormous.
- Is there room for creativity within the rather rigid bounds of style and format?
Yes... it resides within the information modules, focusing on delivering performance
improvement to users. XML is a vehicle to allow cost-effective dissemination of creative
information. Examples of creativity within tight structural constraints abound
within the arts: witness the sonnet, a classical symphony, light sculptures within
- The key is to make information readily retrievable and accessible for
multipurpose uses: training, marketing, proposals, user documentation.
- What is it like writing in a single-source environment? To the authors,
it's much like working off a common server. The database management software
is essentially superimposed over the database, but the authors are basically
working with modules of information.