The LDP Review Project is a "working group" of the Linux Documentation Project, whose goal is to improve the quality of the LDP's documentation. We are approaching that goal from two different angles: a review of newly submitted documentation, and a review of existing documentation. Both projects are at an early stage right now, so we are very much open to your suggestions for improvement.
We have a mailing list established for editors; instructions to subscribe are at http://www.tldp.org/mailinfo.html#maillists.
This document is copyright 2001 by David C. Merrill, Ph.D., and copyright 2004 by Emma Jane Hogbin. It is released under the terms of the GNU Free Documentation License, which is hereby incorporated by reference. Send feedback to <email@example.com>. Please reference the title of this document in your email.
This review project will continue throughout the life of the LDP. The process will act as a front-end quality assurance review for new documentation which is submitted to the LDP. Ideally documents will be reviewed within one week of their submission to the LDP.
Coordinators of this effort will announce to the list or notify individual review members of new document submissions. The coordinators will try to funnel documents to reviewers who have knowledge in the same technical area as the documentation. If the reviewer is not a technical expert in that particular area and needs technical questions answered, there will be a technical expert designated who will be able to address any technical issues or questions.
Once reviewers have agreed to work on a document, they will have one week to complete the review. If they are not able to complete the review within that time frame, they will need to let the coordinator know of their difficulties so that the author can be notified of the problem. Because these reviews need to be conducted rather quickly, there will be times when reviewers will be more able to accept review work.
When reviewing newly submitted documents, refer to the Section 5 and Section 7 portions of this guide for the types of information to verify and correct. As a reviewer, you will need to check the documents out of the CVS  and make any necessary changes. If changes are extensive or if the document has glaringly and fundamentally fatal errors, contact a coordinator to let him or her know what the problems are. Once changes are made, the reviewer will update the minor version number, submit the changes to the CVS, and send the original author a copy of the source.
This project will focus on reviewing documentation that already exists at the LDP. Our goal is to implement a quality management program that makes sure we are supplying up-to-date, accurate, easily read documentation. This process will be ongoing throughout the life of the LDP. Initially, we will try to review all documents currently on the LDP. Once we have made our way through existing documents, we will schedule dates for follow-up reviews. By continually reviewing the documents throughout their life at the LDP, we help make sure readers have the best possible experience with Linux documentation.
In addition to the primary goal of improving the quality of the documentation itself, we will also be gathering data about the collection for storage in some sort of database to facilitate the ongoing management of the collection. However, this stage of the review is still being defined; details about the specifics and how this data will be measured will be added in the future.
Below are some general guidelines that you should follow before you begin reviewing existing documentation for the LDP. Please try to have document reviews completed within two weeks of the time you sign up to review a document.
Because this process is just getting started, there are many documents that need review. The most important thing is that you coordinate your work with the other reviewers. To coordinate the effort, we have set up a mailing list for reviewers.
Notify the editor list (instructions for subscribing are at http://www.tldp.org/mailinfo.html#maillists) before you begin to review a document. We want to make sure your work is directed where it is most needed and where it will be most useful. Of course, you may have a particular area of expertise and that will dictate your choice to some extent. You can ask on the list for an assignment, or you can select one for yourself and just let the mailing list know what you're doing.
Make sure you have the legal right to work on the document. If it is licensed under a free license that specifically grants such rights, you are fine. If not, you need to contact the author and get permission.
If you do not plan to actually change any of the content, but simply report on the document's status, then you don't need permission, regardless of license. Of course, it is still polite, and advisable, to write the author anyway.
If a document is missing a copyright and/or license, it's recommended you advise the author to choose and apply one. More information on licensing is available in the Metadata and Markup Review section.
Make sure the copy you are reviewing is the most current.
If your document includes a URL to an official homepage, visit that page and see if it displays the same version number. If you find the same version number, you are fine. If you find a newer version number, write to the author and ask him or her to please submit the newer version to you.
There are many different ways a document can be reviewed, and you may have the skills to do only one or two types of reviews. It is sometimes useful (and easier) to do each review as a separate pass through the document; Your Mileage May Vary.
The following sections explain the various types of reviews we are conducting. Use these sections as a guide to help you choose the type of review to conduct and to help you conduct the review itself. Again, when you post your review choice to the review list, please specify the type of review you would like to be responsible for.
When an author submits a new document to the LDP, someone monitoring the submission email list will advise the author to post his draft to the discussion list for an initial peer review, prior to publication. Besides determining whether the document thoroughly covers the subject matter, peers may also point out similar work already in the document collection, in which case the new author might want to contact the maintainer of the existing work.
As a member of the review team, you will recognize a peer review document as one the author has submitted to the discussion list, specifically requesting feedback for inclusion of their HOWTO in the collection. This review can be performed by anyone subscribed to the discussion list (www.tldp.org/mailinfo.html#maillists).
Make sure the facts as stated in the document are correct, helpful, and on topic.
To do a technical accuracy review, you really need to know your subject matter, probably as well or better than the original author. Use whatever other documentation is available for your subject, including man pages, program documentation, other printed books, etc. You might also use mailing lists on the topic, asking for third parties to verify certain facts of which you are in doubt.
When doing this type of review, consider if the information is only valid for certain types of hardware or software. If this is the case, make sure to note the limitations of the document within the document, either within the abstract or as a note at the beginning of the document. For example, if the solutions in the document only are relevant for one type or brand of hardware, make sure that that limitation is defined. This will keep readers from trying to apply a certain type of technology to an application or situation where it will not work.
The same should apply for the prerequisite knowledge of the reader. If prior knowledge of a subject is assumed or required, the author should say so somewhere at the beginning of the document, and it's helpful to ask that authors provide a Resource section for further reading, to bring readers that much closer to the required information.
The LDP uses a series of scripts to transform documents into their published format. In order for these scripts to work, documents must use valid markup and include specific metadata. Metadata is information about the document and includes author information, copyright, license and a revision history of the document.
Documents submitted to TLDP document repository must validate as one of the following:
Authors are not required to submit their initial document in one of the required markup languages. A volunteer will be assigned to convert any document which is not submitted in valid markup. Authors must maintain their documents in one of the required formats. Help, of course, is available to authors. The main goal of The Linux Documentation Project is to provide quality documents, not to force authors to learn markup languages.
The following elements are all required:
Because writers come from all types of backgrounds, there may be problems within the documentation that need to be fixed. Writers may be very knowledgeable in their subject areas but not great writers, or they may be excellent writers but not completely fluent in the language of the document. The language review addresses these types of problems by focusing on language issues that make the document easier for the user to read and understand. Some of the problems that may occur within the document are poor sentence structure, grammar, organization, clarity, and spelling.
If you are doing a language review, you should be fluent in the language and the structure of the language. You want to consider both the logic and grammar of the document. Your primary goal in a language review is to identify and correct areas that could lead to confusion for the reader/user of the document. To this end, you can most certainly use language and grammar references such as dictionaries and handbooks when in doubt.
Although this review does address the structure and delivery of the language, you should not attempt to purge the document of individuality and personality in an attempt to make it "sound better" or more technical. Stilted, humorless language and structures are not the goals here. Again, your goal should be to make the document clear, unambiguous, and correct in spelling and grammar.
Items to evaluate:
Once you have completed your review of a document, you should send the updated file and your results back to the Review Coordinator  , and advise the working group you've completed the review. He or she will also need to know which types of review you have completed. The coordinator will need any metrics you have collected, and your notes, and will record your work in the database.
If you have made any modifications to the document, also send your updates to the author or maintainer, as well as the LDP submission list, which is at firstname.lastname@example.org. The subject line should be the title of the document. In the body of your email, please include a note which says something to the effect of, "I am a reviewer for the LDP and am submitting an updated copy of this document on behalf of the author."