Real value (was implementing single-source) - demonstrated (and j ustified)!

[HALL Bill <bill -dot- hall -at- tenix -dot- com>]

I could not leave Andrew Plato's last response (on 14 November) on this
thread unanswered. Technological change over the next five years is probably
going to have more impact on technical writing than has occurred in any
other 50 year period since the invention of the printing press. 

I have a lot of regard for many of Andrew's positions, but here he
demonstrates the difficulty many highly capable people have coming to grips
with the truly revolutionary aspects of new technologies, and his latest
responses give me the opportunity to focus on specific issues of
miscomprehension I also encounter in my own company. (If anyone wants to
explore the issue of changing thought paradigms in technological revolution
specifically, some posts on this can be found on the old Techwr-l archives
on the Oklahoma U server by searching for "Kuhn", "revolution" and
"paradigm" - Thomas Kuhn - The Structure of Scientific Revolutions).

Since 31 October I have attended a range of industry meetings and
conferences which show how radically documentation will change. The
conferences included the Australian branch of Legal XML
(http://www.legalxml.org/) the SGML Asia Pacific 2000 Conference
(http://www.allette.com/xml/), including specifically the SIM users group
(http://www.allette.com/xml/Abstracts/UserGroup-u05.html) and a Defence
Standards forum organised by the Australian Defence Department
(http://www.allette.com/xml/Abstracts/Presentations-p43.html  and
http://www.allette.com/xml/Abstracts/DefenceForum.html). This was followed
by a Tenix conference on innovation in engineering, bringing together
innovators from several divisions to compare notes, and most recently by
DIISM 2000 - the 4th International Conference on Design of Information
infrastructure Systems for Manufacturing 2000
(http://www.msa.cmst.csiro.au/diism2000/). I presented papers at all of
these venues, but I mostly went to listen and discuss technologies and
experiences with peers from other organisations. There are two more
standards-related meetings this week of a government sponsored network of
small and medium enterprises that do Defence related work.

It is worth emphasising that these meetings were all held in Australia - and
given that we are on the opposite side of the globe to most Techwhirlers,
these meetings are only a small sample of what is going on simultaneously in
and Europe.

Now, to Andrew's points:

--

"HALL Bill" wrote...

Secondly, although we have a large volume of data to manage, because the
project has been implemented late in project life cycle, the volume of work
to manage is not that large, as essentially all authoring was complete.
Our costing following the delivery of Ship 4 were based on deductions
against a...

------

Andrew Plato wrote...
This is a BIG difference. Most of your documents done and static. In essence
Bill, you're just implementing a complex version management system.

When do you WRITE? It sounds to me like all this system does is provide a
way to keep all your documents organized. We have a system to handle that
too: a Windows NT file server!

There is a whopping mega huge difference between organizing STATIC text and
working in a dynamic, volatile environment, as is the case in many high-tech
firms. Volatile environments just are not well suited to huge, expensive
documentation management systems.

-----

Bill Hall now replies...

Andrew's first para is spot on. Only a lunatic or a vendor would try to
implement/impose a completely new way of marshalling and managing knowledge
on a new project facing all kinds of project crises, deadlines and chaos.

Tenix had already suffered IT disasters from such lunacy, so the current
project plan includes the initial phase just completed, where we first
implement, test and train using relatively stabile data where we can deal
with our technology learning crises independently from project crises.
We only gain a small ROI in this phase. However, as we gain experience and a
level of comfort with the technology we will begin implementing it at ever
early stages in the project cycle, where the ROI from improving the
efficiency and effectiveness of our use of corporate knowledge will be many
times higher than it can possibly be when most of the project costs have
already been incurred.

With regard to Andrew's comments on the value and potential ROI of
structured authoring and content management in volatile environments, I
offer the following:

There is no more volatile or costly tech writing environment than developing
defense tenders. Costs for 5 - 10 failed tenders must be amortised across
the one or two that are won; schedules for completing the documentation are
absolutely punishing; and to win the bid, the quality of the content has to
be significantly better than the competitors.

As documentation coordinator for a variety of tenders and negotiations I
have seen as much as 25-50% of our writers' keyboard time lost or wasted due
to formatting issues in MS Word, file corruption and loss in the NT server
environment, corruption and loss when trying to amalgamate texts produced by
different authors, paper chases through review and signoff loops, etc. I
hear similar stories from my opposite numbers in our competitors' and
customers' organisations in their RFT development and tender review cycles.
Although none of our organisations have methodologies to accurately measure
the relevant parameters, we estimate that the overall documentation cost
(authoring, production, management and delivery of documents across the
Defence supply chain as well as Defence's internal requirements) for major
defence projects is as much as 5 - 10% of the overall project cost. 

In Australia, with an acquisition budget for major capital projects of about
$A 6.5 BN per year, this would add to $A 300 - 600 M per year. Note: only a
small fraction of the writers are professional tech writers - most are
engineers, managers, active and ex-service personnel.
We also believe that the disciplined implementation and use of structured
authoring and content management technologies could reduce these costs by
20% or more - for savings in the range of $A 100 M or more per year.

------

Andrew Plato wrote...

In my opinion writers should focus 80% to 90% of their effort on content and
20% - 10% on organization/layout/format/design/etc. 

------

Bill Hall replies...

I could not agree more! In our Word environments, our writers, editors and
coordinators are losing up to 50% of their keyboard time dealing with
crashes, formatting and layout issues rather than focussing on the logical
organisation and content that will win tenders for us.

Yes, the Word environment can be somewhat controlled by VBA applications
created by skilled developers, backed up by a significant user education
program and close management.

With the exception of the costs to develop DTDs or schemas (which are best
dealt with as industry rather than proprietary standards), the costs to
develop and manage a Word-based production environment are comparable to
those for managing a structured environment.

Where training is concerned, we found we can train logistic analysts to use
our structured authoring system in a day: half a day to explain how
FrameMaker+SGML works, and half a day to explain how the work-flow
management environment works. Followed by a week of diminishing requirements
for hand-holding, this was all the training they needed in order to
completely rewrite documents. 

Naive authors adapted very well to the regime where the only thing the
authoring environment permitted them to do was add structural elements
allowed within the logical framework of the document types they were working
on and to write ascii text. None complained that they couldn't alter the
predetermined formats.

Where overall knowledge management is concerned, the benefits from
structured authoring in a content management environment greatly outweigh
the costs to develop the DTD/Schema structures which enable this.

------

Andrew Plato wrote...

>From what it sounds like to me, you spend 95% of your time categorizing
text, coding templates, and reorganzing tables.
 
------

Bill Hall replies...

The effort to implement a revolutionary new way of managing knowledge is
significant. However, this is a one-off task. When amortised against the
ongoing maintenance costs for long-lived bodies of relatively standardised
corporate documentation undergoing frequent revisions the cost of the
investment is small in comparison to the gains enabled by a controlled
authoring environment where existing knowledge can be easily located,
reused, and flowed down or across generations of documentation. Where tables
are concerned, our conversion to SGML was a dream. SIM includes library code
for converting RTF formats into SGML/XML. The conversion of WordPerfect
tables (via RTF) to CALS SGML worked perfectly for all tables where authors
used the WordPerfect table function. The only difficulties arose where
authors had manually spaced tables with completely uncontrolled spaces, tab
characters and indent functions. The minor reformatting required in
FrameMaker+SGML was usually accomplished in less than 30 seconds per table,
with only a minute or two required to turn tabbed tables into real tables.

-----

Andrew Plato wrote...

When do you sit down an actually WRITE the content? Is all your time spent
managing and maintaining this system?

-----

Bill Hall replies...

Prior to conversion, we employed a full time data administrator to manage
the WordPerfect system, plus substantial effort on my part to keep it
running. During the peak of our data conversion, validation and value adding
exercise when we had over 6,000 active documents and more than 2,000 active
work items in the workflow management system, our actual data administration
time was down to 4-5 hours a week. The kinds of ad-hoc extracts that would
take a week or two to develop in the WordPerfect merge/macro environment can
now be written in half an hour in the SIM Ace code.

-----

Andrew Plato wrote...

I see kilobytes worth of text from yourself and others about the amazing
value these systems have... how do they make content more accurate? How are
people better writers with these systems? How does it allow people to get
concepts and ideas written more accurately? How does it speed up the process
of gathering information, writing it, formatting it, and then delivering it.

It doesn't. It just gives all the text more structure. Again, if the text is
wrong, it doesn't much matter how well organized it is.

Your system just helps deliver text faster. It does not make the writers
smarter or more capable of understanding the technologies or designs they
have to document. In essence, you have built one gargantuan file server with
a customized front-end application. Great - but you could have done the same
thing with a copy of VSS, FrameMaker, and some decent policies regarding
updating material (and saved about two million dollars).

-----

Bill Hall replies...

Here Andrew seems to be displying his biases, not speaking from any concrete
experience. The 'value adding' phase of our data conversion project
demonstrated this capability beyond dispute. Basically, the task was to
combine the latest Australian and New Zealand versions of equipment
maintenance routines into a single class document for that routine. About
4,000 ship-specific routines (the end product of the automatic conversion
process) were collapsed to about 1,800 dual language class routines and
passed through a complete review and sign-off workflow involving authoring,
peer-review, re-authoring, QA and final delivery processing. In addition to
the basic conversion processing, we also had the added task to review and
upgrade the warnings and cautions in the text. This phase was completed by
4-5 authors in a 3.5 month period. Three of us had prior SGML experience,
two had none.

It is also worth noting that our management system now provides immediate
validation of data types, source references, validation of many data items
against master catalogues, etc. on update, check-in or check-out. This
certainly ensures that critical data items in the text are not wrong!

In this re-authoring process, it was immediately apparent that the original
routines had been very badly written from several points of view other than
the minimal use of warnings and cautions. The content was often deficient
and not well structured logically, and metadata (e.g., parts lists, trigger
conditions, labour resources, etc.) often did not correlate well with the
content of the procedure text. These problems (which had never been noticed
in the word processing environment) were blindingly obvious at a glance when
the content was displayed in the logically structured SGML environment.
Enough writing problems have been identified in the converted documents that
we have taken on the commitment to go back to source data for rewriting over
half of the converted routines. However, even in the 5-10 minutes of
authoring time devoted to each document during the 'value adding' phase, we
have been able to make major improvements by rewriting and adding obviously
missing content. I could go on, but I think this gives the idea. We actually
did a vast amount of (re)writing in a very short time.

Andrew's last point about the cost may still be valid for the older
generation content management systems in the US market, but this is changing
rapidly with the implementation of later generation systems such as the SIM
system we have implemented. In January 1999 the $A fixed price we negotiated
for our full system plus our internal project costs were less than $A 1.5
million (i.e., less than $US 1 M). This price included requirements for a
number of absolutely unique data conversion and delivery requirements
demanded by our existing ANZAC Ship Contract, plus allowances for a number
of risks which were proved to be unwarranted. Today, an even more capable
system (without our unique requirements) could probably be negotiated for a
few hundred thousands of $A. Some time next year, packaged systems may be
available for under $A 100,000.\
 
------

Andrew Plato wrote (with some of my comments interpolated) ...

The ROI on these systems is only valuable if <<is greatest where>>:

 - You have a gargantuan amount of documentation. <<many long-lived
documents conforming to relatively standard structures>>

 - The text is essentially static. <<The documents are long-lived and
subject to frequent revision>>

 - There are few graphics or media. <<There are large volumes of graphics or
media - especially where they are reused across several to many documents
and require management independently from the text>>

 - You have a large number of people working on these documents. <<Two or
more authors likely to work on the same documents>>

 - You need to output the same text to multiple formats <<I completely
agree>>

-----

Bill Hall adds the following to the above list...

 - You can derive corporate benefits from being able to rapidly and
accurately query and retrieve knowledge contained in the documents.

 - You can reduce the volume of text that requires to be written by sharing
and reusing elements of text across numbers of documents.

-----

Andrew Plato continues...

This makes up probably about 150 to 200 companies world-wide. Not to mention
the fact that most firms just outsource this function to document management
firms and forget implementing it in house.

-----

Bill Hall replies...

I would agree with Andrew that today this technology is most applicable to
companies at the high end of the market. Based on my experience

 - three years as the sole writer/documentation manager for a small software
house producing multi-user applications for accounting (generic general
ledger), import-export-warehousing-distribution, insurance broking and
clinical practice management (including patient records) where I wrote the
full suite of user and marketing documentation for all of these products, 

 - two years as technical writer and IS documentation manager for a bank, 

 - followed by more than 10 years for Tenix, 

I would argue that SGML/XML structured authoring and content management
would be cost effective today for most organisations employing more than 5
full time authors - subject to the factors discussed above and the
additional caveats:

 - industry standard DTDs already exist

 - there is a need to produce a number of long-lived documents against these
standards.

-----

Andrew Plato concludes...


Again, I think you and Don are preaching to a small set of very large
companies. These systems simply will not benefit the majority of tech pubs
groups. Better management, tools, and training will.

----

Bill Hall concludes...

Structured authoring and content management represent one of the most
significant revolutions in the whole of human history in the way humans
create, assemble, store and transmit knowledge. Managers like Andrew simply
won't get the right answers if they try to evaluate these technologies
simply as better tools for their existing ways of doing business, when the
technologies are radically changing the whole concept of what writing is and
how recorded knowledge will be used. However, the issues behind this
technological revolution are so fundamental and far reaching that it is
impossible to do them justice in the confines of a space like this. I have
written about 80% of a major paper on the subject, which I hope to complete
in January, with the intent that it will be published free-to-the-web.

Basically, Andrew's comments above are all quite valid in the world view and
technological paradigm he is used to. Unfortunately that world view and the
business judgements founded in it will rapidly become less relevant as the
new and ever less costly technology radically changes the way we manage
knowledge. A kind of Moore's law will apply knowledge management software as
well as to computer hardware, and we all need to be prepared for it in order
to best benefit.

Bill Hall
Documentation Systems Specialist
Integrated Logistic Support
ANZAC Ship Project
Tenix Defence Systems Pty Ltd
Williamstown, Vic. 3016 AUSTRALIA
E-mail: bill -dot- hall -at- tenix -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

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