Re: Documentation Metrics

[David Merrill <dcmerrill@mindspring.com>]

Sandy Harris wrote:
> 
> "David C. Merrill, Ph.D." wrote:
> >
> > I am working on the set of metrics to be used in reviewing our documents.
> 
> Fine idea, especially if, as indicated elsewhere in the thread, it gets
> integrated with matedata and indexing efforts.

Yes, and it will be. I expect to use omf for this, as I said before.

> > Here is what I've come up with so far. Please send me your suggestions to
> > improve this. I have had one person volunteer to help me with this process
> > so far (thanks Nelson), and would like to have at least 2 more volunteers.
> 
> Kevin? Sounds up your alley.
> 
> > 1. Audience Type
> > - application user
> > - programmer
> > - system administrator
> 
> Is a "check all that apply" question, or "indicate the focus"?

Yes. ;->

I was thinking "check all that apply". But it would be okay to indicate
the focus, too.

> > 2. Audience Technical Sophistication
> > - novice
> > - beginner
> > - intermediate
> > - advanced
> 
> Does this need to be broken down by topic? e.g. in my FreeS/WAN
> docs, one might dream of an audience technically sophisticated
> in several areas: Linux admin, cryptography, TCP/IP networking,
> computer security, ...
> 
> Chances of finding such an audience are more-or-less nil. I once
> corrected one of the best-known kernel hackers on an elementary
> crypto misunderstanding he showed in a list post. No question he's
> technically sophisticated, but for purposes of a given doc, perhaps
> not in all relevant ways.

My feeling is that if a random novice is fully capable of understanding
it and using it, then it is at novice level. This has nothing to do with
to whom it is *useful*, but rather with the minimum amount of experience
necessary to understand it.

> A more interesting way, I think, to ask this, might be as a maximum
> and minimum. On a scale of 10, this docs deals with topics up to
> level 8 and provides background down to 3. If you don't already
> know level 2, read other things first.

So we would identify the amount of experience required to understand it,
and the amount of experience at which it is no longer informative? This
is an interesting approach.

> > 9. Currency
> > - badly out of date
> > - slightly out of date
> > - up to date
> 
> There are variants on this. Consider the ipfwadm or ipchains docs.
> One package is almost entirely obsolete, the other perhaps about to be,
> but the doc is (in one sense) not out of date as long as it covers the
> latest version. Certainly this is a different problem that the doc not
> keeping up with the package.

Already dealt with. Add "- obsolete".

One other person has now volunteered to help, so I am in need of only
one more before the survey can begin! Woo hoo!

We should survey a subset of the documents, 20 or so, and then look at
our metrics, and see if they are working for us. If we're struggling to
fit the documents into our metric, maybe it is because the metric is
wrong. But we'll see when we get there.

Thanks to everyone who has offered help and comments.

Regardrs,

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