[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation Metrics
From: "Craig M. Buchek" <[email protected]>
> From: David C. Merrill, Ph.D. [mailto:[email protected]]
> > 1. Audience Type
> > - application user
> > - programmer
> > - system administrator
>
> One document may apply to some or all.
Indicate all that apply.
Most documents only apply to one of these audiences, however. And a good
argument can be made that a HOWTO that doesn't target one of these three
should be split into two.
> > 2. Audience Technical Sophistication
> > - novice
> > - beginner
> > - intermediate
> > - advanced
>
> Some documents may apply to a range of technical audiences.
See #1.
> > 3. Accuracy
> > - awful
> > - poor
> > - fair
> > - good
> > - excellent
>
> The awful and poor sound a bit too mean-spirited. I'd prefer a numeric
> rating from 0 to 10 or something. Actually, numeric ratings (or ranges of
> them) would work well for most of the categories.
You think a "0" rating is less mean-spirited? :/
Seriously, though, this information is not going to be publicized. It is for
my personal use, and perhaps for a few others that help me. And, if the
document is really awful, I have no problem saying so. One thing you can
count on me for is being honest about our shortcomings. How else can we
address them?
I don't have a real problem with a 0-10 rating, except that I think it
implies a level of precision that we can't really achieve. These are
subjective measures, and as such I think 5 categories is sufficient.
> > 9. Currency
> > - badly out of date
> > - slightly out of date
> > - up to date
>
> There is one point to note here. Sometimes a document becomes entirely
> obsolete, not just out of date. Something like ipfwadm being replaced by
> ipchains, or a program that is no longer maintained or needed.
I'll expand this list thusly:
9. Currency
- obsolete
- badly out of date
- slightly out of date
- up to date
Regards,
--
David C. Merrill, Ph.D.
Linux Documentation Project
Collection Editor & Coordinator
www.LinuxDoc.org
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]