RE: Baiting for the single source rant

Subject: RE: Baiting for the single source rant
From: SIANNON -at- VISUS -dot- JNJ -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 5 Sep 2001 10:46:27

Darren Barefoot's comments hit a point I've been wrestling with, and for
which I would greatly appreciate feedback.

The point is that single-sourcing strategies may be more advantageous for
uses other than the production of multiple docs from a single repository of

examples of what I mean:
1) I'm currently working on documentation for internally developed,
maintained and used software. I have little need for reuse of the docs in
multiple formats, but I *do* have concerns about manageability of the
complexity and versioning of the docs. The system is very complex, with
one database and (curently) seven applications with different functions,
processes and levels of human interface, plus interfaces between specific
elements of the system and seven other systems, some of which are on
entirely different platforms. My docs include live, static and
archival/historical, with scopes ranging from system-level to
app/component-level to function-level. Revison control must be maintained
on everything. The docs cannot be versioned in parallel with the software,
parts of which change independently of one another. I have not found a
satisfactory means to combine the docs into a single repository, as it
results in no net benefit thus far. However, I have used the
modularization intrinsic to single-sourcing to reduce the complexity of
upkeep, and I'm 'porting the detailed Maintenance Procedures into a
Helpfile format so the development/maintenance team actually uses it
(improved navigability makes it more likely they'll look something up, and
I only have to update it in one location for them all to get to the current

2) In my last position, I used a single-source database to maintain an
extremely complex and lengthy policy/SOP manual with attached forms and
work aids, and a non-linear table of contents as a winhelp file that needed
to be accessible online and yet protected from modification and

So, have some of you applied single-sourcing strategies to improve
work outside of the classic "1 source, many outputs" paradigm?

How have you applied single-sourcing strategies to improve manageability of
complex docs?

Shauna Iannone
Tech Writer, American Computing Technologies,
currently supporting 3GT CIM at Vistakon
A human being should be able to change a diaper, plan an invasion, butcher
a hog, conn a ship, design a building, write a sonnet, balance accounts,
build a wall, set a bone, comfort the dying, take orders, give orders,
cooperate, act alone, solve equations, analyze a new problem, pitch manure,
program a computer, cook a tasty meal, fight efficiently, die gallantly.
Specialization is for insects.
-- Lazarus Long


A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

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 for more resources and info.

Previous by Author: Re: To utilize or not to utilize
Next by Author: Re: Baiting for the single source rant
Previous by Thread: RE: Baiting for the single source rant
Next by Thread: RE: Baiting for the single source rant

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

Sponsored Ads