Real Value - the real issue: is structured authoring bad?

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

This will be my last word on the topic for a while. I have an urgent
requirement to complete a business case.

The discussion on this issue so far reminds me of the range wars between the
cowboys and the sod busters. A lot more heat has been generated than light -
I think it is unfair to dismiss Andrew Plato as a cowboy - but Andrew is
getting bogged down in an illusory issues of supposed costs and limitations.
Yes, the system Tenix implemented is costly because we are implementing a
technology that is intended to provide a core knowledge management
infrastructure for a multi-divisional company - but it has been cheap enough
that we have been able to pay for it through the ROI on one set of documents
in the tail end of a single project. However, as I will amplify below, the
entry cost to begin structured authoring is trivial and is not a valid issue
for this debate. Also, as I will also document, many technical authors who
have made the shift to structured authoring believes it actually frees them
from a lot of unnecessary baggage in the MS Word environment to focus 100%
of their effort on the actual creative effort to better formulate their
knowledge for the end user.

As several people besides me have mentioned, the starting cost to set up a
structured authoring environment may be as low as the cost of a single-seat
license for FrameMaker+SGML plus learning to use an industry DTD and set of
industry templates.  In the Australian Defence documentation industry, DTDs
are provided by the Defence Publishing Service
(http://www.dod.gov.au/dps/sgml.htm). FrameMaker+SGML EDD and templates for
the authoring apparatus are provided free to the industry by the Absolute
Data Group (http://www.absolutedata.com.au/ - they also sell FrameMaker
licenses and consulting services). These DTD's don't constrain content or an
author's creativity. They do define a range of structural elements and
logical rules for using them in a way that conforms to contractually
mandated formatting standards for our industry. Another (wide-open) option
is to use the DocBook DTD which is also supported with output formatting
services by several of the SGML authoring environments.

A greater issue for authors is the intellectual cost of learning to think
about the knowledge contained in documents in terms of the structural and
logical organisation of the contained knowledge rather than only as stream
of consciousness words appearing on formatted paper or screens. But then,
aren't technical authors supposed to be the absolute masters of learning
about new technology?? I accept that this learning curve cannot be
trivialised, because structured authoring represents a truly revolutionary
change in the writing process (read Thomas Kuhn's classic book on "The
Structure of Scientific Revolutions" @ $9.60 on www.amazon.com). An author
moving into a structured authoring environment for the first time must deal
with all kinds of tacit preconceptions about the mechanics of writing and
what documents are (in most cases probably learned in grammar school). If
these are not consciously understood and dealt with, the inconsistencies
between the paper document paradigm and the structured content paradigm
inevitably generate anxiety and even fear and anger - which are often
expressed in the kind of name-calling exhibited in this thread (e.g., drones
vs cowboys) - and yes, these are all topics in the academic hypertext I am
working on.

In structured authoring environments authors can see text displayed in the
formats that will be produced on output, but have no control over these
formats beyond those provided by emphasis elements or attributes included in
the DTD. Our experienced technical authors love this environment because it
frees them from the continual format hassles they have with MS Word. 

In the Word environment, even with a set of macros to manage links and
paragraph numbering independently from Word's continually faulty functions,
our most experienced authors are still spending at least 30% of their time
repairing and maintaining links and formats. By contrast, in the
FrameMaker+SGML environment they focus 100% of their time distilling their
understanding of complex systems into text and structure that best channels
this knowledge to the Navy personnel who will be using the documentation.

None of our authors who have worked in the FrameMaker+SGML environment would
agree with Andrew that they are drones or that the structured authoring
environment impairs their creativity as technical authors in any way. On the
contrary, it frees them from the continual formatting/production hassles and
crises that inevitably arise in the Word environment.

It is worth noting that even with no consideration having been given to any
of the potential down-stream advantages that our DCMS system will enable, it
has been nearly two years since any new technical manual has been authored
in a non-SGML environment. Where appropriate DTD's exist, all new work is
being done in the SGML environment. Because it is intrinsically difficult to
separate content from formatting codes in an MS Word environment, we do have
to create a business case to justify the labour to convert any manual
formatted in MS Word to SGML. To re-emphasise the point - this is a cost
associated with intrinsic difficulties of the proprietary word environment,
not the structured environment.

To conclude,  where appropriate DTD's and templates, etc. already exist, the
business case to use structured authoring for new documents in place of MS
Word is trivial. In Tenix (and as has been amply documented by many other
Techwhirlers over the years) the cost to maintain Word formats, links and
other apparatus in a long and complex Word document is on the order of 30%
of our most experienced authors' time by comparison to similar work being
performed in a FrameMaker+SGML environment. Authors who have less formal
training with Word (e.g., bid developers) may waste as much as half their
writing time with Word hassles. Yes, better word templates and more training
may reduce this lost time - but the substantial development, training and
management costs must also be costed against authoring productivity in the
same way that they are on the SGML/XML side.

In any event, even after amortising seat license costs, 1-week training
costs with zero productivity, an initial loss of productivity and a 3 month
learning curve in the switch from Word to FrameMaker+SGML; the conservative
ROI is achieved in less than a year even for authors who only achieve a 10%
improvement and only spend 50% of their time actually writing. Obviously,
anyone wanting to make this business case should plug in their own numbers.
However, I think any really fair costing to establish an SGML/XML authoring
environment with an already existing DTD and authoring apparatus against
Word's inefficiencies and what it costs to make Word work at all, will pay
for the structured authoring environment on a seat-by-seat basis in less
than a year.

Obviously, if you have to include the substantial costs to develop a new DTD
and viewing and formatting apparatus for the authoring and delivery
environments the business case is more difficult (but will become less
expensive as more people become skilled in the analytical processes -
intrinsically, these tasks are probably less difficult than it is to develop
robust and reliable MS Word template for complex document types). However,
in many cases the DTDs and authoring apparatus are best developed by an
industry standards consortium or with Government support. For example, I
know of at least three major industry groups working to develop eCommerce
(i.e., XML) standards for bid and contract documentation for project
management enterprises (http://www.legalxml.org/contracts/;
http://cic.vtt.fi/projects/globemen/public.html; http://www.aidn.org.au/;
see also http://www.msa.cmst.csiro.au/diism2000/).

Note, the above arguments include none of the additional returns and
benefits that can be gained from more sophisticated use of structured
documents: e.g., 'single sourcing', sharing and reuse of existing texts,
configuration and content management, sophisticated information retrieval,
data validation, automated processing and document assembly, workflow
management etc., etc. 

These turn technical writing into knowledge management and delivery, and as
I have said previously on this forum, structured authoring represents the
first wave of a technological revolution in the way knowledge is transmitted
which will be even greater (and much faster) than was enabled by the
invention of the printing press.

Hence, the range of issues surrounding structured authoring deserve serious
consideration, discussion, and even substantive action, not name-calling and
application holy wars.

Bill Hall
Documentation Systems Specialist
Integrated Logistic Support
TENIX ANZAC Ship Project
Williamstown, Vic. 3016 AUSTRALIA
Email: 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.