About us   |   Login   |   Register
 

Single-Source from the Reader’s Point of View
by Teresa Mulvihill - 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:

  1. 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.
  2. Investing time into indexing markers by clarifying what and how terms are indexed ensures specific details are easily searched.
  3. 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. 

2 Comments to “Single-Source from the Reader’s Point of View”

  1. Susan says:

    Great article about single-sourcing!

  2. Marie-Louise Flacke says:

    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!

Leave a Reply

Write your comment below: