Re: Single Sourcing

Subject: Re: Single Sourcing
From: Suzanne Townsend <suzyt -at- ISTAR -dot- CA>
Date: Fri, 11 Jun 1999 09:10:27 -0300

Eric wrote:
<snip> how would you organize or structure or write for optimal
single-sourcing? ... I'd really like to hear about writing and
organizational techniques. <snip>

I once inherited a single manual with all the info you describe and had
to turn it into online Help. Here's what I did, which worked pretty
well. The Help needed further breakdown of some topics (too long, too
many subjects in one) and a lot of jumps-and-links finessing, but that
was expected. I'll tell you one thing -- moving it to online help really
makes any organizational/substantive errors in the printed doc stand

1/ Separated the info into 3 manuals/Help systems:
--end-user how-to instructions
--administration how-to (coupled with a Web-based admin GUI)
--programming reference material and API documentation

2/ For each of these, divide into info for setup/one-time-only tasks and
info for ongoing tasks.

3/ For each task, start with an overview. This becomes your Tell Me
Then the procedure, with screenshots. The procedure become your How Do
I, and the screenshot becomes your What's This or other field- or
screen-based Help. Then references to Appendices for further info (which
beomes your Help's "Related Topics" or "see also" -- and I have no
qualms about referencing printed info in Help)

Having said all this, there is in my mind just no such thing as a
single-sourced document -- by the time it goes through its evolutions to
the other delivery format (online to printed or vice versa), the two
items have *different source documents*. And too many of these
evolutions must be done manually (vs using conditional text or other

My jaded $0.02. Best regards,

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Stick with RoboHelp, or upgrade to something else?
Next by Author: Re: HUMOR: Survey of recent TECHWR-L Posts APOLOGY
Previous by Thread: Re: Single Sourcing
Next by Thread: Re: Single Sourcing

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

Sponsored Ads