Re: Documentation Metrics

[David Merrill <dcmerrill@mindspring.com>]

jdd wrote:
> 
> sorry, folks, but I think there is a problem.
> 
> I'm unsure what this discussion is about.
> 
> I think initially it was about knowing what documentation was lacking (to
> try to write it) and giving a help to beginners (initial writing guide)

This thread, "Documentation Metrics", is and has always been about
documentation metrics. The first sentence of the first message is "I am
working on the set of metrics to be used in reviewing our documents."

> if the goal is still of this kind, you can continue to fill pages and
> pages of mails if you want, I can't afford to read it all, but I trust you.
> 
> but if you mean you are going to weight the HOWTO's to know if they are
> good or not an to grades authors on this base, I disagree absolutely.
> 
> knowing if a howto is well written or not is of nearly no interest, at
> least as long as there are yet to be written howto's.

Quantity and quality are both important. It is better to have no HOWTOs
than to have HOWTOs that contain horribly wrong, misleading and
inaccurate information! Please understand that I am *not* saying this is
our situation. I think most of our HOWTOs are reasonably well written
and accurate.

> The only question is : is this howto usefull or not ? is the answer is
> yes, let it live.
> 
> I don't think ldp is allowed to do any real metric on the documentation.

Allowed by whom?

> If you want really to have some kind of judgement on the howto's,
> enventually, you can set online a questionaire asking users: did you read
> the howto ? did you use it ? do you like it ? and that's all

This is also a good idea, and it has been discussed in another thread.

To say that we are trying to "judge" HOWTOs or their authors is to put a
very negative spin on it. What we are trying to do is to get a
manageable "snapshot" of the current state of the collection.

> is for no other reason, the only people able really to meter a howto is a
> people able to write it, and if so he should better work with the author
> than judge him...

Working with the authors is *exactly* what I intend to do. I hope to be
their friend and ally in producing the best possible documentation.

Once the survey of the collection is complete, we will then:

1. Contact authors whose works are obsolete or becoming out of date, and
ask them if they can update it. If they cannot do so because of lack of
time or something else, we will ask them to find a new maintainer, or
allow us to do so.

2. Find fluent speakers of English to correct grammatical and spelling
errors.

3. Possibly archive very obsolete HOWTOs somewhere, or at least make
sure they are marked clearly, so readers know that they apply only to
certain, older versions of software.

4. Continue our work to get all documents converted into DocBook.

And so on. Whatever problems we find, we will deal with as seems
required.

> anyway, try to keep short, trim most of the initial mail in yours
> answers... this thread become unreadable...
> 
> and don't think I under estimate your work. I greatly appreciate all you
> there.

Thank you very much.

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