Re: Single Sourcing - Myth or Salvation?

["Bill Hall" <bill -dot- hall -at- hotkey -dot- net -dot- au>]

Stephen Gillespie expressed a quite reasonable misunderstanding of my
contribution to the latest "single sourcing" thread.

Quoting me:

> "The bottom line is that we implemented the SIM system, converted (and at
> the
> same time basically rewrote) all the documents ... for a total time
> investment of less than a half hour per document"

His request for clarification:

> Good lord, Bill -are you saying that for your single-sourcing project, you
> rewrote all 10,000 documents?! Let's see, doing the math, that's 10,000
> times a half-hour, equals 5,000 'half-hours', or 2,500 hours - is that
> correct?

My answer may help to clarify the power of structured content management:

We used Ship 4 (the latest complete set) as our starting point for the
conversion process (~ 2000 documents).

The original documents were authored as WordPerfect 5.0 merge tables, with a
separate file for each ship (or shore facility) system, and a separate
record in the file for each maintenance procedure against that system. The
record contained all the metadata relating to the management of the
maintenance procedure (e.g., all kinds of resources used, periodicities,
trigger codes, configuration identifiers, etc., etc.). A complete set of
files had to be maintained for each ship as the only way we had any hope of
keeping track of the configuration differences for each ship. Merge/Macro
processes were used to validate key data items and to produce more than 20
different deliverables from the same sets of merge tables. By the time we
began work on the fifth ship set of documents the client was sufficiently
unhappy with the inconsistencies over 8,000 records - soon to be 10,000 -
that we were placed under a serious threat that the fifth ship wouldn't be
accepted as fit for operation if we couldn't deliver a completely consistent
set of documents that would perform flawlessly in their relationally based
maintenance management system. Because the Defence budget was under severe
stress at the time the Navy would have been quite happy to delay acceptance
and reduce the overall cost of the project through our contribution in terms
of liquidated damages. (Hey, people, we are talking about working on a fixed
price contract with heavy duty customers in the real world!).

The solution was executed as follows.

0. We had already been investigating products for a year, so we had a good
idea what the project would cost from hard fought competitive quotes (not
cheap) against a very detailed functional spec for what the system had to
do, which included a draft DTD that clearly identified all of the elements
of information we had to manage and their logical relationships. When it was
clear we had no cheap fix for the magnitude of the problem we faced, we
bought SIM through one of Australia's most capable system integrators who
had a sound reputation and many satisfied customers for IT implementation
(Aspect Computing)

1. An Ace script (Ace is SIM's high-level object oriented application
development language, available free to the Web -
http://www.simdb.com/simdb%20content%2FAbout%20SIM%2FDownloads?LASTQRY=ACE)
was used to automatically convert our WordPerfect merge tables into SGML
instances. The Aspect guys thought the conversion process performed poorly
to convert 97% of the files to a loose DTD that could be edited in
FrameMaker+SGML and only 70% which went straight to our strictly controlled
authoring DTD. The remaining 3% required manual corrections before the
script could move them through to SGML - however the conversion script
clearly identified where and why the conversion failed. Aspect then kept
tinkering with the script until we were ready to start the conversion work
in real-time). The final script was then used to convert 4 ship-sets (~8,000
documents) into SGML for storage and management in the SIM system. This took
only a few hours.

Note - the time taken to develop the conversion script is not included in
the 3,000 hours it took to produce the 5 ship-sets of deliverables - the
risk mitigation process placed this as the first task in the whole
implementation exercise - to prove that automated conversion would work.

2. In most cases where a procedure was performed on Ship 4 (the second ship
for New Zealand) this was selected to be the "single source" master from
which all ship's documents would be produced. (This was the most recently
written, and presumably the most correct version of the procedure).

3. We then determined if the same procedure applied to other configuration
items on the one ship (our best case was with self-contained
air-conditioning units - were the same routine applied to 13 different units
on the one ship). The different configuration identifiers were included in
the one master and the redundant procedures deleted. Pumps and electric
motors were other classes of equipment where many largely redundant routines
could be "collapsed" into one "single-source" master.

4. This was then compared with the latest Australian version (Ship 3) of the
same procedure and all of the language differences between the two records
entered as alternative language specific texts in the one master. "Language"
differences included references to differently identified reference
materials, standing orders, warnings & cautions, and the "gotcha" we missed
in the initial specification for the system: different safety tags and the
fact that the exact same repair parts were given different part numbers by
the two navies because they had been painted different colours (storm grey
vs waikato grey). We ended up with the rule that different language versions
could be applied to any element in the DTD.

Note: except where there was ship specific or navy specific equipment, our
"worst case" for reduction was reducing 4 ship specific documents into 1
class specific document (which will suffice for all 10 ships that will
eventually be delivered). Our best cases were for several procedures
associated with the 12 or 13 self contained air where 56 separate
ship-specific documents were reduced to exactly 1.

5. In the SIM's browser (IE 5) view of the document we verified that all
parts, tools, equipment, materials and the like referenced or obviously
required to be used in the text of the procedure were actually reflected in
the metadata. (In the FrameMaker+SGML environment this only took a couple of
minutes). At least 25% of the documents had clear errors which were fixed on
the fly, and some were so badly written we flagged them for a complete
rewrite. Note that all metadata and SGML structure are automatically
validated on every check in/check out or whenever the author requests it.
Our standard practice was to hit the validate key every time a new part or
equipment ID was entered, as an immediate check for typos. Since all the
related descriptive information was automatically entered this protected us
against entering wrong but valid ID's

6. The document was then checked out to FM+SGML for text editing.

   a. Health and safety issues were stringently vetted since the client had
substantially changed its requirements for meeting OH&S regulations and
standards. Tenix had paid a specialist H&S contractor for the better part of
a year to manually check all documents in printed format to determine where
new H&S warnings and cautions were required. Virtually every record needed
new warnings and cautions. These were added as required by pointing and
clicking from our master list of standardised texts (in some cases the NZ
and AUS versions of the warning used different text or did not apply at all
in one of the languages) in our quick passes through the documents. Also,
because the SIM environment allowed us to retrieve and compare in seconds
all instances of similar procedures, it was clearly apparent that the manual
review had missed 15 to 20% of the cases where warnings or cautions were
clearly required, so these were added. In all cases the wording in each kind
of warning, caution or note was standardised against the master texts held
in a separate FM+SGML file. (Single-sourcing did not allow us to share these
texts from a single common location for maintenance, but we still achieved
total standardisation in seconds by manually clicking and pasting from the
single master file that held all commonly used texts).

   b. we also completely standardised the overall logical structure of the
procedure so it was fully conformant with the concept expressed in the DTD
as well as the explicit rules: e.g., every procedure should fit the same 4
part structure: (1) optionally required "Conditions" which explained the
circumstances under which the maintenance should be performed where
conditions other than simple calendar periodicity triggered the maintenance.
(2) "Preliminary" which included steps required to isolate systems, tagouts,
and job setup. (3) "Task(s)" one or more tasks which to be completed in
performing the maintenance. (4) "Completion" steps to clean up after the job
and restore the equipment to service (generally the specific reverse of the
preliminary steps). Again, a rigorous and thorough inspection of the logical
structure of the document could be completed in a few seconds by comparing
the structural and formatted views of the document in FM+SGML. A lot of
sentence editing and standardisation was also achieved in the 2-5 minute
pass through the texts to fix problems that no one had ever seen in 5 years
of working with the WordPerfect flat files.

7. Edited documents were then checked in and instantly flagged for peer
review.

8. (At this point our annotation functions had not yet been implemented,
so...) peers printed the browser view and marked up any glitches missed by
the original authors and signed off that the review was complete. We have
implemented SIM to make it impossible for an author to peer review his/her
own work.

9. When the supervisor is satisfied that enough peers have reviewed the
document (given our deadline pressure only one peer was required to do a
review) the document is released for rework and it is instantly placed in
the original author's worklist.

10. The author makes the required corrections and the document is released
for QA review.

11. The QA reviewer can either accept the result and release it for delivery
processing or bounce the document back for more rework.

12. The automatic delivery processing to produce a complete fleet set of
documents conforming to an absolutely unique data delivery standard (a
combination of comma delimited ascii flat files and HTML procedure tests -
with all ship and language specific variants appropriately resolved) only
takes an hour or two.

The workflow above is actually a simplification of what we actually did, but
the bottom line is that after taking a couple of months to do the first
hundred or so documents as we debugged the system, it took 4-5 us a total of
approximately 3000 person hours to produce the complete set of documentation
for the Ship 5 delivery deadline (equivalent to producing 10,000 individual
documents). The start was slow due to the teething problems with a totally
new system, but once these issues were solved, it took us less than a half
hour of human eye and keyboard time to process the average document from the
initial raw SGML to the point of delivery - to deliver a very substantial
improvement in consistency and quality across the entire documentation set.

Subsequent to the initial delivery we have implemented a number of
additional functions, including annotations with two way links to source
data, and writing the client into the pre-delivery electronic review and
signoff workflow. Our customer is very happy with the result, we are likely
to get more documentation business, and it is costing us much less to
deliver that result than when we were working in a flat file word processing
environment. More details can be found in my Technical Communication paper
http://www.tenix.com/PDFLibrary/91.pdf.

The implementation cost us more than $US 500,000, but we also had a number
of unique difficulties to resolve (dual languages, configuration management,
automatic validation against several different external sources of master
data, production of a complex relational data delivery conforming to an
absolutely unique interchange specification being the main ones other than a
very real "drop dead date"). And with that, we have barely scratched the
surface of SIM's inherent capabilities, which I am beginning to explore for
more extensive corporate uses in a new cross-divisional role.

As a plug for SIM: SAIC (about 300 in the Fortune 500 list) distributes,
implements and already supports SIM in the US (for a number of existing
clients) and Europe out of their Annapolis Maryland offices. Contact details
are available on the SIM web site: http://www.simdb.com. Usual disclaimers
apply. The note is personal, doesn't represent my employer. I am a happy
user of the products mentioned, and don't hold shares in or work for the
companies whose products I mentioned.

Bill Hall
Documentation Systems Analyst
Strategy and Development
Tenix Defence
Nelson House, Nelson Place
Williamstown, Vic. 3016
Australia
http://www.tenix.com
mailto:bill -dot- hall -at- tenix -dot- com (work)
mailto:bill -dot- hall -at- hotkey -dot- net -dot- au (home)
------------------------------------------
Information is not knowledge
Knowledge is not wisdom
Wisdom is not truth
Truth is not beauty
Beauty is not love
Love is not music
Music is THE BEST
-----------------------------
(Zappa - Packard Goose)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 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.