Subject:
Re: Beginning of outline for policies
From:
David Lawyer ####@####.####
Date:
19 May 2002 03:12:37 -0000
Message-Id: <20020518194510.A409@lafn.org>
On Wed, May 15, 2002 at 09:22:59PM -0400, Tabatha Persad wrote:
> On Wednesday 15 May 2002 18:04, David Lawyer wrote:
> >
> > Another comment is that I'm not sure if LDP should have any
> > "editors". Most of them could be called "reviewers". The word
> > "editor" sounds too dictatorial. What about saying that Joy is the
> > "quality control" person. Her title would just be "quality
> > control". What else could we call her besides editor?
I didn't realize that her full title is "Review Coordinator and
Collection Editor". So since "editor" not all that prominent in her
title, I think it's OK for her to continue using her present title. But
I still don't want to call reviewers "editors". See below.
>
> As I address some of your comments, please don't consider me
> adversarial. I'd like to understand your point of view...
Ditto for me.
>
> I didn't know the term "editor" was an issue. That's really what we
> do, or at least what I signed up to do when I spoke with Joy. It's my
> understanding that I AM editing these documents I pick up for grammar
> and spelling. Anything beyond those two items would require review
> with the author.
Many of our documents are copyrighted so that only the author may make
modifications, including spelling corrections. If someone does make
such changes, they need to either send the author the changed sgml
source or let the author know what was changed. We are not like most
other publishers where the author has assigned the copyright to the
publisher and the publisher is fully free to make changes.
> Just a review implies, "This is what I found wrong, what are YOU going
> to do about it?" Correcting a typo isn't a review process, it's an
> editing process.
True, but we should seldom need to physically correct typos. Instead of
correcting them, just point them out to the author and let the author
make the correction. This is good feedback to the author to help
him/her avoid the same typos in the future. If one finds some spelling
mistakes, the review should stop the review and ask the author to use a
spell checker.
So I don't think that we should normally be directly correcting typos.
The author should do it. Also, I've gotten feedback about various typos
from readers. I ask for such feedback. It's one way to lessen the
workload for reviewers. A reader can easily spot typos and we need to
make is easy for them to give such feedback.
> Also, my goal is not to remove the author's voice, but make it
> clearer, and I take that responsibility seriously, since I want to
> help the quality of the documentation I also use from the LDP.
I think we all share this goal (as well as other goals).
> > > 1. Overview of Editing Processes * Introduction - This could
> > > contain some information about the fact that the LDP has a team of
> > > editors to
> >
> > What team? If we had such a team, why would Joy need to try to
> > recruit someone for the PHP-HOWTO.
>
> When I last checked there were approximately 30 volunteer
> editors/reviewers listed at the LDP. I can't speak for the rest of
> them, but I am readily available, have a high bandwidth, and joined
> the project to get involved for a very long time to come.
I just checked also. There are 28 such people and you're one of them.
So is David Merrill and Joy Goodreau. But I checked the document list
on the LDP-DB and sorted by review status. Of the 411 HOWTOs (including
minis), only 4 have been reviewed and 5 are currently undergoing review.
We are making a new start (there was a previous review effort a while
ago) and I don't mean to belittle our work. But we have a long ways to
go.
> I can only surmise that in the case of the PHP-HOWTO, a simple
> language review would not be sufficient for this document. It will
> probably require the help of someone or a group who are familiar with
> the technical aspects of PHP to address this doc, or re-create it
> altogether.
I don't fully agree. Here's what I found near the start of this HOWTO:
Each and every computer programmer knows why PHP is the best. Ask
your nearby computer programmer.
Only PHP will prevail in the 21st and 22nd century!
Even a cursory knowledge of programming and/or common sense tells one
the above is hyperbole. Or it's meant to be humorous but it's not clear
that it's humor from the context.
> > > It might take the scare out of the process to know that editors
> > > are working to help improve quality and readability, not hack
> > > apart the author's work. A good area to establish the mission of
> > > the LDP and why this is beneficial to the community.
> >
> > Just have no editors. Problem solved.
>
> Do you propose then that the editing group (of volunteers) be
> disbanded?
Of course not. Just call them reviewers.
> Given the current state of much of the documentation, is it so bad
> that there is a team willing to take on this responsibility? In my
> case, getting rid of editors means that unless I am an author, I don't
> have anything to contribute to the LDP.
I suggest calling them reviewers, not just because this name is more in
tune with what they do, but also because is has a better connotation.
Maybe it's just me but I've had bad experiences with editors in the
commercial world. I know others have too.
> > [Regarding Language Review]
> > This can often be combined with Technical Review. We could just
> > call it review for short. There's also a brief review by sampling
> > parts of the doc. Since we are lucky if we can get any kind of
> > review on all the docs, we should not worry too much about
> > classifying reviews by type. There's a whole gamut of types of
> > reviews.
>
> I'd have to agree to disagree with you on this point. There are many
> documents that I am not technically adept to edit/review. I am
> certainly not going to follow the instructions on every HOWTO to
> determine whether the syntax and procedure of each and every one is
> valid. I do feel that I am skilled enough to perform the language
> reviews for English documents.
But this doesn't contradict what I said above. I said that they often
can be combined (say in 40% ?? of the situations). Also, a technical
review can be done by someone who is not an expert in the topic of the
HOWTO. For example, the PHP HOWTO. Just a general knowledge of
programming languages would help. It's best to find someone who is an
expert but if you can find no such person willing to review, then you
need to compromise.
[snip]
> > > 2. Procedure for New Submissions * How long does the review take
> > > once I submit my document?
> >
> > This will vary, but if it's too long, then the doc is published with
> > only a cursory review. No need to specify this.
>
I meant that we don't need to specify it in a formal policy document,
but that it's should be specified from time-to=time as conditions
change. An author that submits a doc should get some idea of how long
it's going to take to review it and get it on the mirrors. Perhaps
respond immediately with a form letter to the author. This letter
would thank the author for the submission and tell about how long the
review is expected to take, etc.
[snip]
> Once we are at a point where everything in the collection has been
> reviewed and quality improved, this responsibility might level off
> somewhat.
Even if we could just do a sample-review of all docs it would help.
I mean just sample say 10% of each doc. One problem will be that
some authors will have a lot of things wrong with their doc. Fixing
them might take even more time than it took to write the doc originally
and they may not have the time available to do this. Solution: Recruit
more authors, including ones willing to take over existing docs, etc.
> > They can look at my mini-HOWTO on LinuxDoc :-)
>
> It's a great doc too! Linuxdoc was the first dtd I learned. I
> realize we have a reference page for resources on this subject too, so
> having resources in this proposed doc could be duplication of effort.
>
> > > * Discussing recommendations with your editor.
> >
> > Presently, we have no editor for each doc.
>
> No, but once one of us volunteers to pick it up and assign ourselves
> the work, there is an editor for THAT doc, and a starting point for
> the author, who could definitely seek help from another
> editor/reviewer or the list if seeking another opinion.
Some reviewers (I mean editors :-) may not want to commit themselves to
following the doc in the future.
[snip]
> I re-read the Manifesto yesterday evening to make
> sure I hadn't missed anything, and then I noticed that you are the
> author of the document
Other people wrote it originally. I only revised it after a lot of
discussion on the list. I tried to make it state what was the consensus
of the group, even in cases where I disagreed. Everybody pretty much
agreed with the final result. There was some additional revision of it
proposed at an LDP meeting but we need to go over that on this list. I
once posted a request for comment on the first section but got no
response. But I'll soon try again.
David Lawyer
