Re: Documentation Metrics

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

As others have already noted, developing metrics on documentation quality is
notoriously difficult to do in any objective way.

Writing for defence clients, we have a series of mandated standards to
conform to with regard to styles, layout, structure, etc., and it is fairly
easy to see whether individual authors conform to these or not. The
difference between good writing and conformant writing is a much more
difficult issue - on this we have to listen to client complaints and
compliments (we have received both in good measure - in the past plenty of
the former and now plenty of the latter which is being translated into
additional business).

Our major turnaround was not through any approach to implement metrics but
was achieved by moving our authoring from word processing to structured
authoring in SGML in an electronic workflow environment. When our reviews
were on paper, they took forever and were often lost or simply passed over
to get the tic. The electronic workflow forces each and every document done
through a serious peer review and correction cycle, and the structure views
very clearly highlight organisational problems and focus both writers and
reviewers on the individual elements of exposition. Peer review and rework
is then followed by a real QA review, and then a client review (all on the
electronic workflow environment) before the documents are released for
publication. All of our original deliverables were processed through this
write/review/rewrite/QA processes as a by-product of our data conversion
process.

Also, not only are we producing far better documentation than we did in the
past, but we have probably doubled the productivity of our authors.
Unfortunately for business cases, we never had any reliable productivity
metrics before implementing our controlled authoring environment. Now our
content management system allows us to measure things to a gnats eyebrow,
but we still don't have any good comparative measures for the past
productivity. However, eliminating paper chases, formatting hassles, and
lost work crashes - and being able to finish the entire writing cycle for a
new document in a few days rather than taking weeks or months for paper
reviews means the authors haven't forgotten their thinking between the
original authoring, review feedback and rework - all of which saves time and
improves quality.

Because we had many unique issues (dual languages, data validation
requirements, converting thousands of legacy documents from the word
processing environment, and unique electronic delivery requirements) the
implementation cost over $500,000 US, but we have easily recovered our
investment even from the tail end of the project after most of the writing
was finished.

In any event, the point I am making is that quality control up front is MUCH
more important than after the fact metrics.

Viva la XML, structured authoring and content management!

For those who may be unaware of my previous posts on the ANZAC Ship Project
maintenance routines, our authoring environment is FrameMaker+SGML with
content management and workflow provided by RMIT's SIM system. And, no, SIM
is not some academic wank from the bottom of the world. It may be of
interest that SIM has recently been rebranded as TeraText (it is readily
scaleable to build and index multi-terabyte databases concurrently with
querying the same databases), and is being marketed and supported in North
America and Europe by SAIC's TeraText division(http://www.teratext.com). My
understanding is that the TeraText division now has more than 100 staff with
TeraText skills as a result of application's importance to the defense
intelligence community. TeraText also has all the core capabilities that
make it a very good content management environment with very flash response
times for check-in/check-out and data+document validation. It is also comes
equipped with a good enough web server to host the entire RMIT University
Web and intranet (more than 30,000 students and staff).

Bill Hall
Documentation Systems Analyst
Strategy and Development
Tenix Defence
Williamstown, Vic. 3016
Australia
http://www.tenix.com/
mailto:bill -dot- hall -at- tenix -dot- com
------------------------------------------
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 out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l

Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.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.