167 lines
6.6 KiB
HTML
167 lines
6.6 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: Documentation Metrics -->
|
|
<!--X-From-R13: Rnivq [reevyy <qpzreevyyNzvaqfcevat.pbz> -->
|
|
<!--X-Date: Mon, 16 Oct 2000 23:02:23 -0400 (EDT) -->
|
|
<!--X-Message-Id: 39EBC1CA.32C0CC52@mindspring.com -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 001c01c037a4$ed795550$6401a8c0@nc.ehomecare.com -->
|
|
<!--X-Reference: 39EBBC98.8DD727C4@storm.ca -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: Documentation Metrics</title>
|
|
<link rev="made" href="mailto:dcmerrill@mindspring.com">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg04111.html">Date Prev</a>][<a href="msg04113.html">Date Next</a>][<a href="msg04111.html">Thread Prev</a>][<a href="msg04113.html">Thread Next</a>][<a href="maillist.html#04112">Date Index</a>][<a href="threads.html#04112">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: Documentation Metrics</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: Sandy Harris <<A HREF="mailto:sandy@storm.ca">sandy@storm.ca</A>></li>
|
|
<li><em>Subject</em>: Re: Documentation Metrics</li>
|
|
<li><em>From</em>: David Merrill <<A HREF="mailto:dcmerrill@mindspring.com">dcmerrill@mindspring.com</A>></li>
|
|
<li><em>Date</em>: Mon, 16 Oct 2000 23:04:42 -0400</li>
|
|
<li><em>Cc</em>: LDP-Discuss <<A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A>></li>
|
|
<li><em>Old-return-path</em>: dcmerrill@mindspring.com</li>
|
|
<li><em>References</em>: <<a href="msg04101.html">001c01c037a4$ed795550$6401a8c0@nc.ehomecare.com</a>> <<a href="msg04111.html">39EBBC98.8DD727C4@storm.ca</a>></li>
|
|
<li><em>Resent-date</em>: Mon, 16 Oct 2000 23:02:23 -0400 (EDT)</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <Av6iSB.A.kKG.EH865@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>Sender</em>: dmerrill</li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
Sandy Harris wrote:
|
|
>
|
|
> "David C. Merrill, Ph.D." wrote:
|
|
>
|
|
> > I am working on the set of metrics to be used in reviewing our documents.
|
|
>
|
|
> One thing I'd wonder about is whether any useful metrics can be
|
|
> generated automatically.
|
|
>
|
|
> There's a whole literature on readability indexes based on statistical
|
|
> analysis of things like words per sentence, letters per word. Some of
|
|
> the key work was Lorinda Cherry and others in the Writers' Workbench
|
|
> project at Bell Labs.
|
|
>
|
|
> There was a Reader's Workbench project at one point, U of Utah I
|
|
> think, with an ex-Bell Labs person from the Programmer's Workbench
|
|
> (make and ancestors of CVS) project involved. Anyone know where that
|
|
> went? Is the software available somewhere? Did they publish papers?
|
|
>
|
|
> There are other things one could measure.
|
|
>
|
|
> Frequency of technical terms (first cut at a definition is words not
|
|
> in some general-purpose dictionary) or of such terms minus a standard
|
|
> list (Linux, ipchains, RFC, ...), or terms neither on list nor in
|
|
> glossary (oops!).
|
|
>
|
|
> Another variant would use not a standard English dictionary, but one
|
|
> of the dictionaries developed for use with non-native speakers.
|
|
> <A HREF="http://www.boeing.com/assocproducts/sechecker/se.html">http://www.boeing.com/assocproducts/sechecker/se.html</A>
|
|
>
|
|
> Frequency of words which indicate rhetorical structure -- therefore,
|
|
> however, whereas, except, .. -- or of constructions that reference
|
|
> other parts of text -- either pronouns such as 'it' or 'this', or
|
|
> non-specific nouns that refer back to more exact descriptions. In
|
|
> many contexts, phrases like 'the device' or 'the interrupt' function
|
|
> this way.
|
|
>
|
|
> Frequency of various whateverML tags, and their level of nesting.
|
|
> Nested lists inside a table structure under a level six heading?
|
|
> Methinks I see a problem. One H1 tag followed by 14 K of text with
|
|
> only two links in it? That's problematic too.
|
|
>
|
|
> Measuring such things precisely and figuring out all the implications
|
|
> is a big project. I'd guess there are half a dozen potential theses
|
|
> in it. On the other hand, an afternoon of Perl hacking might be enough
|
|
> to provide some interesting results.
|
|
>
|
|
> My guess would be that at least some of the objectively, automatically
|
|
> measurable statistical properties of text would correlate with some
|
|
> of the judgements we make -- clear vs. confusing, basic vs. advanced,
|
|
> etc.
|
|
>
|
|
> I'd love to have a tool that tells me that, compared to some sample
|
|
> that covers related docs (say, HowTos for administrators) and that
|
|
> users rate as well-written, my docs are measurably different in
|
|
> specific ways.
|
|
|
|
This all sounds interesting, but I would rather start with a more
|
|
pragmatic approach for now. I wish I had the time to investigate this,
|
|
just to satisfy my curiosity.
|
|
|
|
Regards,
|
|
|
|
--
|
|
David C. Merrill, Ph.D.
|
|
Linux Documentation Project
|
|
Collection Editor & Coordinator
|
|
www.LinuxDoc.org
|
|
|
|
|
|
--
|
|
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
|
|
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="04101" href="msg04101.html">Documentation Metrics</a></strong>
|
|
<ul><li><em>From:</em> "David C. Merrill, Ph.D." <dcmerrill@mindspring.com></li></ul></li>
|
|
<li><strong><a name="04111" href="msg04111.html">Re: Documentation Metrics</a></strong>
|
|
<ul><li><em>From:</em> Sandy Harris <sandy@storm.ca></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg04111.html">Re: Documentation Metrics</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg04113.html">Re: Documentation Metrics</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg04111.html">Re: Documentation Metrics</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg04113.html">Re: Documentation Metrics</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#04112"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#04112"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|