[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation Metrics

From: "Craig M. Buchek" <[email protected]>
> "David C. Merrill, Ph.D." wrote:
>
> >>> 2. Audience Technical Sophistication
> >>> - novice
> >>> - beginner
> >>> - intermediate
> >>> - advanced
>
> >> 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.
>
> Yes.  That's what I was trying to get at when I suggested a range.  I've
> seen a couple publishing companies use such a range on the back covers of
> their books to indicate the technical level of the intended audience.

I like it. Okay, I've incorporated all the suggestions that I liked and
agreed with.

The current metrics are:

1. General Information
- title (NEW)
- author's name and email
- current maintainer's name and email, if different from the author
- version, if there is one
- date of last update

2. Audience Type
- application user
- programmer
- system administrator

Indicate all that apply.

3. Audience Technical Sophistication
- novice
- beginner
- intermediate
- advanced

Indicate all that apply.

This should be seen as a "range" of technical sophistication. The low end
represents the required amount of experience to understand the document and
the high end represents the amount of experience at which the document is no
longer really informative.

Backgrounders would probably rate "novice".

An introductory text might rate "novice - beginner".

An advanced tips text might rate "intermediate - advanced".

A really comprehensive text that covers everything from background
information to advanced tips and techniques could conceivably rate "novice -
advanced".

4. Accuracy
- awful
- poor
- fair
- good
- excellent

5. Comprehensiveness
- sketchy (a few bare facts)
- adequate (good amount of information)
- comprehensive (complete coverage of the subject)

6. Source Format
- DocBook SGML
- DocBook XML (none currently, I think)
- LinuxDoc SGML
- HTML
- text
- texinfo
- whatever else you find

Indicate the source format only, not all available formats. Our goal is to
get all documentation into formats that allow meta-data, indexing, and
output in many formats. This metric lets us know how well we're doing.

7. Style
- obtuse
- readable
- highly accessible

This should be viewed in the context of the intended audience. How easy is
it for the reader to glean the important information? Is it obscured by
random thoughts interjected at random intervals? Does the author go off on
tangents?

Rate down for excessive use of techspeak and/or jargon.

Rate up for clear explanations of concepts.

8. Language (grammar and spelling)
- awful
- poor
- fair
- good
- excellent

9. Currency
- obsolete
- badly out of date
- slightly out of date
- up to date

(NEW)
10. License
- Link/reference to the LDPL
- An inserted copy of some old version of the LDPL
- GPL
- GFDL
- OPL (indicate options used)
- whatever else you find

(NEW)
11. Keywords
These will be used in generating meta-data.

(NEW)
12. Required Reading
List any HOWTOs that contain information necessary to understanding this
one. For example, the Adv-Bash-Scr-HOWTO requires you to understand the
contents of the Bash-Prog-Intro-HOWTO.

The categorical list of HOWTOs available at
http://www.linuxdoc.org/HOWTO/HOWTO-INDEX/categories.html will help you
identify HOWTOs in the same subject area.

(NEW)
13. References
List any other HOWTOs that are referred to or linked to.

(NEW)
14. Topic(s)
Indicate the topic area under which the document belongs. Please use the
topic areas I already developed (see the link in 12, above), but indicate
errors or omissions.

One goal is to use metrics 2, 3, and 14 to get an idea of the general
coverage our documents provide. Ideally, we should have documents for novice
through advanced, both users and administrators (where appropriate), in all
topic areas. Let's see how close we are!

(NEW)
15. Comments
Make note of anything else you wish. Give praise and criticism where
appropriate.

If I missed anybody's comments, please mail me privately rather than
rehashing it on the list.


The plan:

1. Get a clear picture - establish metrics
   1a. Determine metrics (done, I think!)
   1b. Measure.
   1c. Adjust metrics if we see the need.
2. Triage
   2a. Identify the worst problems.
   2b. Develop plan of attack to address them.
   2c. Identify licensing issues (non-modifiable works).
3. Problem Resolution
   3a. Give feedback to authors.
   3b. Seek additional HOWTOs where needed.
   3c. Edit documents myself for grammar, language and speling erorrs.
4. Ongoing Management (rinse, repeat).

I'll be contacting those who volunteered to help privately. This project
could generate lots of mail and I don't think the whole list wants to see
it.


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]