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

Re: Documentation Metrics

To: "LDP-Discuss" <[email protected]>
Subject: Re: Documentation Metrics
From: "David C. Merrill, Ph.D." <[email protected]>
Date: Tue, 17 Oct 2000 16:14:22 -0400
Old-return-path: [email protected]
References: <[email protected]>
Resent-date: Tue, 17 Oct 2000 16:12:16 -0400 (EDT)
Resent-from: [email protected]
Resent-message-id: <XnJjrB.A.KbH.mML75@murphy>
Resent-sender: [email protected]

*revised, "beta" metrics are at the end of the post*

Thanks again to everyone who has sent, and is continuing to send,
suggestions for improvements to these metrics. They are starting to look
really great!

I can think of several more things I'd like to measure eventually, such as
the quality of the DocBook markup, level of indexing, and such. I'm sure
some of you can, too, but that would be putting the cart before the horse.
We have more serious problems to address first. Unless you have a real
burning request, and can justify it to me, we're going to go ahead with what
we've got.

This project could take quite awhile, depending on how much time each of us
has to give it and how many people help. There are 319 HOWTOs, according to
sorted_howtos.html, so it's a pretty big job. Consider this yet another call
for volunteers to help. It's a very important project and will hopefully
result in a greatly improved LDP. You don't need any special skills, just a
willingness to help! I know I said I'd like 2-3 helpers previously, but I
realized that I really need more than that. It's okay if you only do one
HOWTO. If you're a HOWTO author, you could provide metrics on your own
HOWTO. I trust you to rate your own work accurately. This alone would be a
big help, and would spread the workload widely.

From: "Martin WHEELER" <[email protected]>
> On Mon, 16 Oct 2000, David C. Merrill, Ph.D. wrote:
>
> > I am working on the set of metrics to be used in reviewing our
documents.
> >
> > 5. Source Format
> > - DocBook SGML
> > - DocBook XML (none currently, I think)
> > - LinuxDoc SGML
> > - HTML
> > - text
> > - texinfo
> > - whatever else you find
>
> suggestion:
>
> 5. Source Format
>    * SGML - DocBook
>           - Linuxdoc
>           - other
>    * XML  - DocBook
>           - other
>    * HTML - 2.0
>           - 3.2
>           - 4.0 (strict/transitional)
>           - 4.01
>           - other
>    * text
>    * texinfo
>    * other

I will store the file formats using the more hierarchical format you show
above. It makes sense. However, the distinction in HTML dialects is not
important to me. Any document whose source is HTML will need conversion to
DocBook.

AFAIK, there are no "other" SGML DTDs currently in use. If we find some,
though, we'll identify them as such.

> > 8. General Information
> > - 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
>
> suggestion:
>
> add - markup editor  (as well as author & maintainer)

Good idea. The metrics have been updated as follows:

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

NOTE: The markup editor usually applies to DocBook documents. They should be
tagged using the <othercredit> element.

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 (Base / DTD )
-SGML
  o DocBook
  o LinuxDoc
-XML
  o DocBook
- HTML
- text
- texinfo

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

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

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

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.

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

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!

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

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]

References:
- Re: Documentation Metrics
  - From: Martin WHEELER <[email protected]>

Prev by Date: Re: Cataloging LDP White Paper: Categorization
Next by Date: Re: Documentation Metrics
Previous by thread: Re: Documentation Metrics
Next by thread: Re: Documentation Metrics
Index(es):
- Date
- Thread