editors: Thread: Review process?

Hello, editors!

First, thank you for all the hard work you have done to create,
collect, and edit Linux documentation.  I am one of the direct
beneficiaries of this work.

I'm writing because I need to understand a few things about the review
process that aren't spelled out in the LDP Reviewer HOWTO or elsewhere
on the site, as far as I can tell.  I can summarize with these simple
questions:

1. How does a review start?
2. What does a review entail?
3. When is the review done?

In more detail:

1. How does a review start?

Who decides when a review needs to be done?  How often can reviews be
requested?  Some control needs to exist over this process, or else a
single Microsoft employee could keep us busy reviewing documents for
years at a time.

2. What does a review entail?

Obviously, a review involves several members of the editors mailing
list reading the document and giving their suggestions on how to
improve it.  The real question here is, who decides what changes
_must_ be made to a document in order for it to remain on the LDP
site?

3. When is the review done?

As in Aesop's fable about riding a donkey, it's impossible to please
everyone.  Discussion could quite conceivably go on for years without
agreement.  Who gets to decide when the discussion is over?

Thank you for your time!

-VAL

On Tue, 2003-12-09 at 23:10, Val Henson wrote:
> First, thank you for all the hard work you have done to create,
> collect, and edit Linux documentation.  I am one of the direct
> beneficiaries of this work.

You're welcome, and I know what you mean!  I benefited from the LDP
enough to take on this crazy job!  :D  Oh heck, I love it, who am I
kidding.

> 1. How does a review start?
> 
> Who decides when a review needs to be done?  How often can reviews be
> requested?  Some control needs to exist over this process, or else a
> single Microsoft employee could keep us busy reviewing documents for
> years at a time.

Any new document submitted is immediately redirected to the discussion
list for peer review, with a recommendation to not wait more than a week
for feedback and then move on to tech and language review.

Currently we're kind of doing a sweep of the whole collection, but I'd
been hoping everyone would start at the oldest first.  Perhaps some of
the folks on the discussion list were hoping to use their expertise on a
specific work instead of just grabbing the older stuff, which is
reasonable to expect, and may be why yours came up.  

But once we've done some of the bigger cleanup, I'd like to set review
terms, based on the type of content.  Some topics covered change
technologies more frequently, and should be updated more often than
others.  We have yet to determine groupings for the terms, but it's hard
to implement without a backend...it's on my to-do list. :D

> 2. What does a review entail?
> 
> Obviously, a review involves several members of the editors mailing
> list reading the document and giving their suggestions on how to
> improve it.  The real question here is, who decides what changes
> _must_ be made to a document in order for it to remain on the LDP
> site?

Peer reviews shouldn't last more than a week, and should be about:
1.  This is covered/not covered in another document at LDP and should be
merged somehow.
2.  This would be a great doc if you made sure to mention <blah>.
3.  I reviewed your doc and saw you only have plain text, can I help
with markup?
4.  You forgot to document this important <blah> which is integral to
understanding something.

Technical reviews really cover technical and factual accuracy.  In
simple terms:  Does the solution(s) provided resolve the issue?

Language reviews are the bulk of the work and require both author and
reviewer to work together, and agree on revisions:
1.  Spelling and grammar are checked, alternative wordings provided to
help with clarity.  Substantive word misspellings can sometimes be
tracked with a style guide (a little text file we use to document our
conventions for this doc as we go, for consistency).
2.  Markup is checked to make sure it's valid, parses, processes.  Also
we try and add tags that could have been utilized and weren't, and
correct any tags used incorrectly.  We will also do the markup if the
author is unable to find assistance or do it themselves.
3.  Necessary metadata is included and updated.  New versions are always
indicated as such, and reviews are noted in the revision histories.  We
ensure copyright and license are in place, and discuss choices with
authors who are unsure.  All new documents must use some form of
license, the 3 main choices today being GFDL, OPL and Creative Commons.
4.  If we don't understand an author's meaning anywhere, we ask for
clarification to make the necessary corrections.  

I may have missed one or two things, but that's the general gist of it.

The most important thing an author can do to keep the document at the
LDP is make sure to keep it up to date.  It seems like in the past
authors have dumped their work off with us, only to never appear again,
and in some cases, abandon it.

We don't get rid of anything without peer and reviewer discussion first,
whether an author is still in touch with LDP or not.  Soon we will
archive out of date documents so that they can be run through the review
process or come out altogether.  As much input is requested as possible
before anything is completely removed though.

> 3. When is the review done?
> 
> As in Aesop's fable about riding a donkey, it's impossible to please
> everyone.  Discussion could quite conceivably go on for years without
> agreement.  Who gets to decide when the discussion is over?

I usually tell new authors to give peer review responses up to a week. 
There has usually been enough feedback provided by that time - sometimes
it takes more or less time (as you know!), but usually by then we can
all agree on what needs to happen with it.

The tech review time has never been really defined, but I ask the
reviewers to keep in constant communiation with the author.  Really it
shouldn't take longer than a week either.  Any longer and a simple note
to the author usually suffices.

The language review has been defined as taking a week.  Of course this
depends on the size of the work being reviewed.  We try and be thorough
in terms of the things we review (as noted above), and clarify with the
author as we do the review, via email.  When we're done, we ask the
author to review our proposed changes prior to submission, and then it
can be published.  

OF NOTE:
All proposed revisions are subject to negotiation, and we don't make
drastic changes.  Our goal is for you, the author, to keep your voice,
but still respect your audience.  I've always had a policy to hear an
author's objection to any change I propose.  And any changes I propose
in grammar or phrasing are backed with reasons, ALWAYS.

I can't definitively say when the discussion is over, but it's always
been as a result of agreement so far.  :D

I hope that gives you a better picture of what we try and do.  If I've
missed anything or you have any other questions, give me a holler!

Tab

-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)