Re: Documentation Metrics

Subject: Re: Documentation Metrics
From: Sandy Harris <pashley -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 05 Jun 2002 22:33:51 -0400


Paul Goble wrote:
>
> > * What criteria do you use to verify if a document is good, in the
> > absence of user feedback ?
>
> The only reliable metric I've found has been usability testing, ...

I suspect various other measurements can be worthwhile if used correctly.
Of course they cannot substitute for testing, but they might tell you
something interesting.

The Writer's Workbench project at Bell Labs in the 70s had several ways
to collect statistics on text samples. I've forgotten the details, but
they provided tools to measure things like words per sentence, letters
or syllables per word, ratio of active to passive verbs, and to
calculate several different readability scores including the "fog index".

The recommended way to use them was to compare fairly large samples.
You get a sample of stuff that your audience (or client, or boss) rates
as well written and, if possible also a sample of stuff they hate.
Compare the statistics on your text to those from the samples. See
if there are interesting differences.

Of course there are other things you could measure.

Frequency of hyperlinks per 1000 words, and proportion that point
to glossary, rest of your doc, outside. Size of glossary and index
compared to text of document set.

Headers per 1000 words or per chapter. Ratio of level N headers to
N+1. Number of figures, tables, lists, procedures, ... Callouts
per figure. Depth of nesting for headers and lists.

Frequency of words not in some standard list of English words,
perhaps a dictionary written for high school students or second
language learners. Proportion of those words that aren't in the
glossary either.

My guess is many of these would turn out to be useless in most
cases, but any of them might sometimes highlight interesting
differences between your docs and whatever you compared to.


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


References:
Re: Documentation Metrics: From: Paul Goble

Previous by Author: Re: When users want jargon
Next by Author: Re: Good grammar and style review book?
Previous by Thread: Re: Documentation Metrics
Next by Thread: Re: Documentation Metrics


What this post helpful? Share it with friends and colleagues:


Sponsored Ads