[<<] [<] Page 1 of 1 [>] [>>] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[<<] [<] Page 1 of 1 [>] [>>] |