TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
My company has a simple approach to measuring documentation quality:
Quality is defined by our customers. That is, if our documentation
end-users say that the documentation is good, then it is good.
This requires us to ask our end-users for their feedback, for which we
conduct phone surveys. We get an in-house statistician to tell us what a
statistically-significant sample size would be, and then we phone that
number of end users.
The documents we last surveyed were a Tutorial and a task-oriented
Reference for a Windows-based drawing program for drawing chemical
structures. The goal of the documents, as defined in the doc plan, was
to get the average user "up and running" and able to draw the chemical
structures they were interested in with only occasional reference to the
Reference manual for those more obscure functions not covered in the
Tutorial.
Given the goals, we asked the following questions:
TUTORIAL
1. Did you use the Tutorial?
2. If you used it, could you then go on to create your own structures
with only limited use of the Reference manual?
3. We also asked users to give a grade from A -- F and to then give any
number of free-form comments.
REFERENCE
1. Did you use the Reference?
2. Did it contain the information you needed?
3. If not, what was missing?
4. How did you look for information (ToC, Index, Browse, etc.)?
5. Was it easy to find the information you needed?
6. We also asked users to give a grade from A -- F and to then give any
number of free-form comments.
By asking strictly defined questions, we were able to tabulate the
results and draw conclusions. For example, for the Reference question,
"Was it easy to find the information you needed?", 86% said Yes and 14%
said No. Given the 80/20 rule, this told us that our efforts in indexing
and generating the ToC were adequate and that we didn't need to divert
additional resources to this effort but merely maintain the existing
effort. (Additional free-form comments by end users provided a wealth of
new index entries that we subsequently added.)
Surveying like this does take a *large* amount of effort in planning and
preparation, finding end-user addresses, sending introductory letters,
making the calls, tabulating the results, and so on. However, given that
our company spends hundreds of thousands of dollars every year in
tech-writer salaries, print costs, and so on, it seems essential to us to
determine that what we end up providing is actually of value to the
end-user.
Trevor Grayling
Manager, ISIS End-User Documentation
MDL Information Systems, Inc.
trevor -at- mdli -dot- com
I am a consulting manager, responsible for user and
technical documentation. I am trying to identify a more
(okay, so *more* presupposes that we actually do it
now, which isn't really the case) effective way to
measure the quality and functionality of our
documentation (primarily software doc). One of the
methods I'm looking into is function points.
Our company recently purchased the LBMS Methodology,
and I am responsible for developing a documentation
template, including guidelines and techniques. As a
result of this task, I am working closely with our chief
methodologist. We have discussed using function points
(although we assume that we would have to assign
arbitrary values) since that has worked well on application
development projects in the past.
Has anyone used function points to measure the quality
of documentation, and do you have any advice for
getting started? I am interested in any other metrics (for
measuring quality only). I would appreciate any comments,
suggestions, or recommendations you could give me.
Thanks!
Karen Mayberry
Levi, Ray & Shoup, Inc.
Springfield, IL
217-793-3800, x. 713
Lrsmail!Lrsspfld!Lrs!Mayberry -at- Attmail -dot- com
