Subject:
Proposed Review HOWTO (full text)
From:
David Lawyer ####@####.####
Date:
3 Mar 2005 06:10:54 -0000
Message-Id: <20050303055359.GC2569@lafn.org>
Here's what I propose, now that we are looking for reviewers. It's
short and strives to make reviewing a lot easier, faster, and more
informal.
David Lawyer
Review mini-HOWTO
David S. Lawyer ####@####.####
March, 2005
____________________________________________________________
Table of Contents
1. Introduction
2. Contact the Author First
3. Types of Reviews
3.1 Technical vs Language Reviews
3.2 Sampling Method of Review
4. Writing up a Review
5. Review Purpose
6. Review Policy
7. Problem Documents
______________________________________________________________________
1. Introduction
Reviews of documents help The Linux Documentation Project (LDP)
achieve its goal of high quality documentation One form of review is
just feedback from readers. If readers find errors or have suggestion
for improvement, they just email the author. If the author doesn't
respond, then the reader should post a message to the LDP discuss
list.
Another form of review is done by LDP volunteers. Especially
important is reviewing new documents before they are accepted. In
some cases in the past, LDP has accepted poorly written documents
because they were never reviewed properly (if at all). A number of
these have been removed from the collection.
If you want to help, go to http://tldp.org and find a HOWTO you're
interested in and review it. You don't need to be an expert in the
topic you review but you should be able to write clearly since you'll
be passing judgement on the clarity of writing by others. If you want
to be part of the review team contact the review coordinator and join
the discuss mailing list.
2. Contact the Author First
Before spending too much time reviewing a document, contact the author
and ask for a reply. In many cases, authors and maintainers don't
respond to emails for various reasons. They may have changed or lost
their email address, fallen behind with answering email, be pressed
for time, or could even be ill or dead. It would be a shame to do a
lot of work reviewing a HOWTO, only to find that the author can't be
contacted or doesn't have the time to improve on it. In such cases,
you may want to try to find a new author yourself. One thought is to
contact a local Linux User Group and see if anyone there is willing to
help.
Before looking for a new author, you should check if the license
allows modification. If it doesn't, then try hard to contact the
author an get permission to modify. As a last resort, the doc will
need to be rewritten from scratch. Even if the license allows
modification, it's polite to also get the permission of the author.
3. Types of Reviews
3.1. Technical vs Language Reviews
A person who doesn't understand the technical aspects of a doc very
well, can sometimes do a Language Review to check for clarity,
grammar, etc. Then someone who has technical knowledge of the subject
can do a technical review. But it's more efficient for someone with
both technical and language knowledge to simply review the doc,
checking for clarity, grammar, organization, relevance, and technical
accuracy. But it's easier to find people to do language reviews and
in some cases they might reject a doc based on language alone (or off-
topic content), which reduces the workload of technical reviewers.
3.2. Sampling Method of Review
The sampling method saves time. It's done by just sampling a few
parts of a doc. It the samples are mostly of poor quality then the
doc is sent back to the author for rewriting. If the samples are all
excellent, then the doc is accepted. If the samples are somewhere in
between these two extremes, then some more samples are made until it's
clear as to whether or not the doc should be accepted.
For a sampling review, the reviewer may just sample topics that they
know well. This allows people to review who are not up to speed on
all the contents of the doc. One may use "grep -i" to search for
modern tools to see if the HOWTO is up-to-gate.
When a doc fails a sampling review, some authors have just fixed the
errors found in the sample and resubmitted the doc again. This should
not be permitted, since the sampling indicates with high probability
that the rest of the document needs a lot of work too. The author
should carefully rework the whole doc before resubmitting.
4. Writing up a Review
The format of writing up your review is up to you. You could just add
your comments, clearly marked, like in a mailing list, to the text of
the HOWTO. Or you could just include some excerpts from the HOWTO.
Or you could just refer to various sections of the HOWTO without
copying any of it. It would be useful to write a paragraph describing
the HOWTO in general (without describing specific errors) that would
briefly address its quality and scope.
5. Review Purpose
A purpose of a full review is to help the author improve a HOWTO. The
reviewer points out errors, lack of clarity, suggestions about adding
new material, organization, etc. The author has the freedom to not
always follow the suggestions, or to implement some of them in a
different way. Both the author and the reviewer are expected to be
reasonable and to compromise if necessary. The author will often give
the reviewer credit somewhere in the HOWTO.
Another purpose of review is that of screening new (and old) HOWTOs.
Should a new HOWTO be accepted? Do some HOWTOs need to be rewritten
and/or marked as obsolete, etc? Do some HOWTOs cover about the same
topic and need to be merged? Did a newer HOWTO make an older one
obsolete?
6. Review Policy
Bear in mind that many HOWTOs are written by people to whom English is
a second language. The grammar need not be perfect but the concepts
should be clearly explained. If new material is needed, suggest it.
Either British or American spelling is OK. If a HOWTO is mainly
applicable to one distribution, one type of hardware, one desktop
environment, or certain versions, this needs to be clearly implied in
some way. You can't expect the author to know all the major
distributions. But authors are expected to use spell checkers and
proofread their HOWTOS for clarity and typos.
You needn't be an expert to do a review. If you don't know the topic
too well, then you'll need to learn it better, not just from the doc
you are reviewing but from other sources as well. If there are
procedures suggested in the HOWTO, you should try them out to see it
they work OK.
7. Problem Documents
Some documents are submitted to LDP which need extensive rework. LDP
volunteers at present just don't have the time to provide extensive
help to authors. So it's the author's task to provide a well written,
error-free document. Perhaps authors can find someone on their own to
help them with it.
A few HOWTOs are so poorly written that they never should have been
accepted in the first place. If you find one like this, you may not
want to take the time to explain all the mistakes, since this would be
almost like writing a new HOWTO. Just suggest that it needs removing
and why. Other HOWTOs are hopelessly out-of-date and need rewriting.
On the positive side, the LDP is receiving a steady stream of new and
updated docs at a rate of one every few days. So there are lots of
docs that are up-to-date as well as many that are not.
