RE: Baiting for the single source rant

[SIANNON -at- VISUS -dot- JNJ -dot- com]

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 
verbiage.

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 
copy).

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 
redistribution.
 

So,....how 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?


Thanks!
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.  http://ieeepcs.org/2001/

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

---
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.