Single Source: Yay, Nay, or TBD?

Subject: Single Source: Yay, Nay, or TBD?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 19 Oct 2004 09:11:00 -0400

Anne Allaire Burke wondered: <<... what people think of single sourcing. I am on the fence about it -- leaning heavily towards not yet convinced that it "works" for all documentation types.>>

In theory, SS does indeed work for all documentation types. In practice, the difficulty that often prevents success lies in two areas: defining what you really mean by "single-sourcing", and defining what needs you're trying to meet. Misunderstanding either area produces ineffective results.

<<For example, I don't like the idea of converting my hardcopy user guide into an identical online version.>>

That's not SS; it's shovelware. SS is about writing material that should be identical (e.g., the description of the contents of a field or the meaning of a checkbox) only once, then reusing it everywhere where that same information would be appropriate. Since you'll present the same information in the same way in both locations, you can reuse that information rather than having to write different (and potentially contradictory) chunks of info. for each use.

SS is also about providing alternatives to that otherwise identical information where reusing identical information would be inappropriate. For example, if you're single sourcing a chunk of content for both a Wizard (or similar computerized assistance) and a printed manual, the Wizard might replace a screenshot equipped with callout arrows with a circle drawn around each relevant interface item, in sequence, to point out what the user must do next. The same information is pointed to in the same sequence, but in very different ways.

<<I feel that online documentation (Help, etc.) is used and learned differently (from the user perspective) than it's hardcopy counterparts.>>

Unquestionably. Among other things, online help is always contextual (the right help appears for each specific context), whereas printed matter is noncontextual (i.e., you have to seek out relevant topics rather than having them automatically presented to you). There are other differences, such as the fact that poorly designed online help usually competes with the software for control of your screen whereas a printed manual lies outside the screen, but it's the contextual aspect that is probably most significant.

Another thing to keep in mind: Both online help and printed docs are inherently unsatisfactory because they take the user out of their task (getting something accomplished), and replace that with a new task (finding information). There's a growing move towards embedded assistance which provides as much help as possible directly within the interface so that users leave their actual task as rarely as possible. This is difficult to single-source in the traditional sense, because it ties more tightly to the interface, but it can still be done with thought and care.

--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed!
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Question on on-demand publishing?
Next by Author: Sentence structure?
Previous by Thread: Re: Single Source: Yay, Nay, or TBD?
Next by Thread: Re: Single Source: Yay, Nay, or TBD?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads