Re: Documentation Metrics

["David C. Merrill, Ph.D." <dcmerrill@mindspring.com>]

From: "Craig M. Buchek" <cbuchek@linuxgruven.com>
> From: David C. Merrill, Ph.D. [mailto:dcmerrill@mindspring.com]
> > 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 ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org