Re: Documentation Metrics

[Sandy Harris <sandy@storm.ca>]

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

> 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"?
 
> 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.

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


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org