When to single source

Subject: When to single source
From: ltilling -at- fairisaac -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 25 Feb 2002 12:2:42

I like the idea of single sourcing. In fact, I recommended it back at my
last company. This was a case of a new product that would be offered in an
asp mode. They wanted all online documentation initially, but wanted the
option of producing printed docs in the future. I researched various
options. We were already using Frame for our docs of existing products
(workstation, shrink-wrapped variety) and I convinced them to purchase
WebWorks Publisher so that we had our options open on output. Initially the
docs would be primarily API and reference information for a proprietary
scripting language. They planned to eventually develop a GUI down the

I left that company almost 2 years ago. I work within a larger Tech Pubs
department, which is divided into teams assigned to various products. Our
company produces some very different types of products. One team provides
docs for an asp-type product where the docs change regularly and they
rarely print anything. There are extensive APIs and variations of them.
Another works on mainframe-style products that have some interface that can
be used on a Windows workstation, but run primarily in mainframe
environments. Mine are somewhat in-between -- used on a Windows
client-server system and what users create with them can then be used to
generate source code for a variety of platforms. It is a pretty complex
system, requiring six books currently and three different Help files.

Our department has been investigating single sourcing for over a year now.
Our manager wants WebWorks to become our standrad for developing Help --
all Help. While I think singe sourcing is great in some situations, I can't
help but question how effective it would be for some of our projects. Our
core product is a mature one that releases one major update a year, but
there is usually a lot of re-working and re-writing of material for one of
these releases. Sometimes material is taken from one manual and re-located
to another. There is a lot of technical information that must be provided
to users so that they can use the software effectively and get the results
they want. It will take a lot of work to set this up and it is very
unlikely that we would make small changes later and then re-generate
anything before the next major release.

I know how to do this technically -- conditional text, mapping, etc. But I
am uncomfortable with comprimising the quality of the printed docs or
online Help that already exist. I have yet to see a good example of
extensive single-sourced documentation for a mature product where you have
good quality for both -- the online Help functions well as a true Help
system and the manual doesn't read like a series of Help topics printed to
paper. To me, singled-sourced docs should be transparent to the reader --
they should give the impression that each was created for its own context.

Does anyone know of any good examples? Especially ones where the source
files are available.

Leslie Tilling
Tech Pubs Team Lead

Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.

Previous by Author: Re: recovered (I think)
Next by Author: Help! Translation and graphics?
Previous by Thread: What She Actually Said
Next by Thread: RE: He said...She said...He said...etc. (Was Re: What's A TW Got To DO-- To Get A Job Around Here?!)

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

Sponsored Ads