Single-Source from the Reader’s Point of View
by - March 22nd, 2008
Documentation written for single-sourcing (topic based, like that found in DITA) has great potential for efficiency. Writing once and publishing in many publications (Developer Guides, User Guides, etc.) and many formats (pdf, html, HTMLHelp, etc.) turns into cost and time savings.
However, these efficiencies can cause inefficiencies for the users. Many online help users complain they cannot find the information they need while using the search function. Readers are more likely to comprehend texts with a classical book architecture, an architecture which is often sacrificed in single sourced documents and online Help files. When texts are cohesive, readers are more likely to consider information to be clear, well organized and easy to follow.
For comprehensibility, it is essential to have a manual review, even when composing is partially automated. As technical communicators, we must resist system efficiency as an overarching goal. Building a document topic by topic without a comprehensive outline (or table of contents) creates an unsearchable, incomprehensible manuscript. We still need to incorporate classical structures and cohesive devices during the document planning stage.
Luckily, we have several solutions for integrating cohesive devices into single sourced texts:
- Defining a clear navigation by way of a table of contents in the document planning stage allows writers and readers a map for placing and finding needed information quickly.
- Investing time into indexing markers by clarifying what and how terms are indexed ensures specific details are easily searched.
- Incorporating a solid review process with both technical and non-technical reviewers provides vital feedback from outside the documentation department.
The last point may be the most difficult to implement in a single-source environment. Organizations look to Wikis for an easy-to-use solution. However, Wikis have shortcomings, the biggest one being its incompatibility with single-source formats.
LiveTechDocs provides an easy to use web-based solution, allowing reviewers to view the XML single-source as the reader will view it. This solution, bridges the gap between technology and reader comprehension before a document goes to final publication.

March 24th, 2008 at 9:40 am
Great article about single-sourcing!
March 25th, 2008 at 12:51 am
Your comment…
Thanks for this article. Highly needed. I’ll disseminate it to Master Students in Multilingual and Multimedia Tech Comm at the University of Rennes (France).
Having spent some time analysing user’s guides designed with XML, we came to the conclusion there is lot of cleaning needed!
Some hard copy manuals (based on XML) are making a fool of the end-users!