Re: Single Sourcing

[Suzanne Townsend <suzyt -at- ISTAR -dot- CA>]

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
out!

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
About.
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
macros).

My jaded $0.02. Best regards,
--Suzanne

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