Subject:
Informational: Our Review Process
From:
Tabatha Marshall ####@####.####
Date:
12 Nov 2003 01:28:03 -0000
Message-Id: <1068600454.17265.8.camel@mysticchild>
Hi all,
As promised, I wanted to take some time to explain the review processes
we currently have in place for new and existing documentation.
Some of you may already notice some interesting threads on our
discussion list today. I have this unexplainable urge to get everyone
fired up for a good cause. I'm just too much of a geek, I guess! :D
We currently have no automation whatsoever, no database, no place to
keep notes - we have CVS and our mailing lists for the time being. I've
been trying for about a year now to get something in place, not just for
reviews, but overall, and it looks like we're starting to get
somewhere. So as I explain the current processes, and as you follow the
discussion about some of the things we wish for, please share your
thoughts with me. I have a couple of people volunteering to provide
something whether or not the LDP uses it, and I think it will benefit
the reviewers most of all, so all feedback is GOOD!
On to the processes. I'm going to split it into new documents vs.
existing documents.
NEW DOCUMENTS:
When a new document comes in, the review coordinator should be the first
to touch it. If it hasn't been done already, we ask that all new
authors submit their draft to the discussion list, so that it can
undergo a peer review. I tell them to wait up to, but not longer than a
week for feedback and opinion. Sometimes we already have coverage, and
it's more appropriate for the author to contribute to someone else's
work, or maybe someone suggested something was missing, and that the
author really needs this in there for the document to be optimal.
Usually if there's no response in the first few days, we'll be getting
back the same file with no changes, but that's fine.
I instruct the authors to resubmit to the submission list after this
stage, informing them I will post this to the editor's list. I always
assure them if no one picks up the document to edit, I will work on it
myself, but I'm hoping that those days will be fewer and farther
between!
Okay, so now I've posted it, and one of you wants to dig in. The first
one who responds to the editor's list gets to do the review. If you
accept it, your goal is to try and complete the review in a week.
However, it's fine to let the author know if you will be longer because
you are waiting for information or it's a rather exhaustive job.
When you accept the document, you should send an email to the author
(you can cc me if you want, but it's not necessary), letting him/her
know you will be performing the review. You should let them know what
you will be looking for, what you will actually correct, what you will
ask the author to correct, and when you expect to complete your review.
When editing a file, I find it helpful to make a copy of the file to
work on. If the file is called SomeHOWTO.sgml I'll make a copy called
SomeHOWTO-copy.sgml and work on the copy. I have a Linux command called
"diff" that compares one document against another and can redirect the
information to a file, which I usually supply to the author. If you're
unable to do this, you can simply send the original and the copy back
and ask the author or myself to perform the diff.
Here's what we look for:
Markup - Not everyone's going to know how to work with this at first, so
if you don't, just let me know and I'll review the markup after you're
done with the rest. Most of our work comes in as SGML or XML, but we
also have some that come in as text or html that need to be converted.
There are a few of us who can take care of that if you are unable to,
but you are welcome to do so if you learn DocBook or Linuxdoc markup.
Authors often omit tags in many places where they could have been used,
and people who are willing to help with clarifying the document by
changing the markup to present the information better are always
helpful.
Spelling - Feel free to correct spelling and punctuation. I have
noticed that most of you take the same editing approach as I do. You
should consider keeping a text file with your editorial notes, which you
can use as somewhat of a style guide, and give to the author.
Grammar - If you see anything obvious, correct it for the author, and
report your changes, explaining your reasons (usually clarity). If it's
something you're afraid will change the context of what the author is
trying to say, simply report this to the author and ask for
clarification.
Technical - We have few people who are able to do technical reviews, and
I'm hoping this is rectified once we have a document management system
in place. Technical issues could be reported on the document even by
readers, so the author can fix them. In the meantime, all I can say is
if you have the skills and tools to try doing what the author suggests,
go for it! Otherwise, just be on the lookout for anything that may not
make sense to the average reader and ask the author to clarify.
Other - There are many things that won't be pigeon-holed into any of the
above. If there is anything you're unsure of, just run it by me and
I'll let you know.
Also, look for these:
Metadata - All howtos usually contain <articleinfo> or <bookinfo>, which
provide the author's name, email address, date of publication, revision
history, and an abstract which should clearly describe the scope of the
document. If you take a tour through CVS and look at some of the source
files for more recent documents, you'll easily spot this information.
Copyright & License - We ask that all authors provide a copyright and a
"free" license, such as the GNU Free Documentation License (GFDL -
www.gnu.org/copyleft/fdl.html) or the Open Publication License (OPL -
www.opencontent.org/openpub/), to protect their rights. If you run into
any issues, please contact me and I'll help on that.
Resources - If an author seems to assume prerequisite experience or
knowledge before someone can use his/her work, this should be stated
clearly. Wherever possible the author should provide links for more
information on what is required.
Once you've edited what you can, send the file back to the author (give
to me for a diff file if you need to, and I'll send it back to you),
asking him to address any other things you've noted, as per the above
guidelines. The author will work on it and send it back to you. Have
one more look, and if it's met all the above criteria (technical being
the exception), send it to me. I'll forward it to Greg via the
submission list advising who's reviewed it, and he'll add it to the
collection.
That's it for new ones!
EXISTING DOCUMENTS:
If you want to gain some experience first, this is a great place to
start because there's a lot less pressure than with a new document.
Here, if you go through the collection and find a document you think you
can review, and it appears outdated or has lots of spelling/grammar
issues (we have a lot of ESL authors), you're welcome to take it on.
Pick one, and let our mailing list know which one you're doing. Before
you send a message to the author, you can take a look at your leisure,
make some notes for yourself about what you think you'll need to
discuss.
I've run into situations where I've picked up an existing doc and went
ahead and done the editing, sent the author my revision copy and diff
file, written a big long email outlining my changes (and why), and
anything he/she needs to address, only to find out the email bounces.
Best bet is to just get an idea of the things it needs help with, and
then contact the author with that much, advising that you've been
assigned to review it (self-assigned, however you want to say it!). If
you don't get a response in a reasonable amount of time, or it bounces,
let me know and we'll try and hunt the author down.
If you do make contact, simply let him know the same thing you would for
a new review, except applicable to the existing work. You can let them
know that this is a regular process, and proceed with the review as you
would with a new document, submitting the final back to me for addition.
Again, the nice thing about working on existing documentation is we have
tons more than what comes in new. Our priority is always on the new
stuff, but we really need to make a dent in what we have already. So
you are all encouraged to jump right in whenever you're ready!
I think I'll leave it here, hoping I've covered everything, and let you
absorb all of it. Add me to your IM lists or email me and start asking
questions anytime!
Thanks for joining us!
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)
