Differences between current version and predecessor to the previous major change of HowToLDPReviewerHOWTO.
Other diffs: Previous Revision, Previous Author, or view the Annotated Edit History
| Newer page: | version 2 | Last edited on Tuesday, October 26, 2004 10:08:51 am | by AristotlePagaltzis | |
| Older page: | version 1 | Last edited on Friday, June 7, 2002 1:06:54 am | by perry | Revert |
@@ -1,384 +1 @@
-Linux Documentation Project Reviewer HOWTO
-!!!Linux Documentation Project Reviewer HOWTO
-!David Merrill
-
-david@lupercalia.net
-
-
-!Joy Yokley
-
-jyokley@us.ibm.com
-
-
-
-2001-05-12
-
-
-__Revision History__Revision 1..12001-05-12Revised by: DCMMinor bugfixes.Revision 1.02001-05-01Revised by: jyInitial release.
-
-
-
-
-
-This document will help you review LDP documentation.
-It includes procedures, tips and techniques to make the process easier.
-
-
-
-
-
-----; __Table of Contents__; 1. Introduction: ; 1.1. Copyright and License; 2. Reviewing Newly Submitted Documentation; 3. Reviewing Existing Documentation: ; 3.1. Choosing a Document; 3.2. License Issues; 3.3. Working With the Latest Version; 3.4. Picking a Review to Conduct; 4. Technical Accuracy Review; 5. Language Review; 6. Reporting Your Results
-!!!1. Introduction
-
-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 at
- ''http://www.lupercalia.net/mailman/listinfo/ldp-review''.
-
-----
-!!1.1. Copyright and License
-
-This document is copyright 2001 by David C. Merrill, Ph.D., and is released under the
-terms of the GNU Free Documentation License, which is hereby incorporated by reference.
-Send feedback to
-''david@lupercalia.net''.
-
-
-----
-!!!2. Reviewing Newly Submitted Documentation
-
-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 4 and
-Section 5 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.
-
-----
-!!!3. Reviewing Existing Documentation
-
-This project will focus on reviewing documentation that already exists on 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 on the LDP, we help make sure that readers have
-the best 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.
-
-----
-!!3.1. Choosing 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 ldp-review list, which is currently housed at
- ''http://www.lupercalia.net/mailman/listinfo/ldp-review'',
-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 us know what you're doing.
-
-
-----
-!!3.2. License Issues
-
-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.
-
-----
-!!3.3. Working With the Latest Version
-
-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.
-
-----
-!!3.4. Picking a Review to Conduct
-
-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.
-
-----
-!!!4. Technical Accuracy Review
-
-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.
-
-----
-!!!5. Language Review
-
-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:
-
-
-
-
-
-
-*
-
-__Spelling. __ Spelling should conform to a standardized English spelling of terms. For words that are new
-to the language and not yet standardized (e.g. technical Linux terminology that is generally accepted
-in the community), follow the most common spelling for the term.
-
-
-
-
-
-
-__Note__
-
-Because there are two generally accepted forms of English, this review should
-not privilege American English spellings over British English spellings, or vice-versa. For example, if the
-author is writes British English and uses the word "realise", you should not change the spelling of
-the word to "realize" just because you speak/write American English.
-
-
-*
-*
-
-__Grammar. __ For the purposes of this review, grammar should address issues such as standards of subject/verb agreement,
-pronoun/antecedent agreement, etc. One of the common and confusing mistakes made in HOWTOs is unclear pronoun antecedents.
-
-
-
-For example, to say, "You will need to set several parameters in the config file to make it compile correctly.
-The ones you choose to set make a big difference." In this example it sounds like the config file is what is compiling and
-it takes a re-reading of the phrase for it to be clear that "The ones" refers to the parameters.
-
-
-
-Along these same lines, many authors writing for the LDP use smiley faces and exclamation points where they
-would never be accepted in formal documentation or grammar handbooks. The general rule to follow
-at this time is to leave the smiley faces and gratuitous punctuation marks in place unless they interfere with
-the reader's understanding of the concepts being explained. The rationale behind this is to protect the more conversational
-tone of the LDP documentation.
-
-
-*
-*
-
-__Capitalization. __ The word "HOWTO" should always be in full caps with no hyphen.
-Also, the document title should always be in title case. This means that first words in a title are always capitalized.
-The only words not capitalized in a title are prepositions, articles, and proper nouns which would not be capitalized otherwise (e.g.
-insmod). Other capitalization should follow rules of standard English.
-
-
-*
-*
-
-__Clarity. __ Judgements on clarity are sometimes difficult to make. One successful strategey in
-evaluating clarity is asking the question "If I did not already know this information, would
-the explanation be clear from this document." If it is confusing to you and you already generally
-understand what the author is trying to say, then there is a good chance that the explanation is
-really confusing for someone reading the document for the first time. If you run across this situation,
-and you don't really know how to correct the technical explanation, or you are afraid your changes might
-affect the meaning of the document, ask for help from a technical expert. If no technical expert is available
-or no one responds to your requests, note the needed changes in
-the review and mark that these concerns need to be addressed in the technical review.
-
-
-*
-*
-
-__Organization. __ In some cases the document would really benefit from a different structure. You should address these
-issues when they interfere with the understanding of the information within the document. If a document gives
-background information after a procedure has been performed, this may well be too late for the reader to
-fully consider the information he or she needs before performing the task. Look for document organization that might
-confuse or mislead the reader. These will be the types of issues you want to address. Once these are identified, it
-may be worthwhile to let the author know your rationale and discuss major changes with him or her.
-
-
-*
-*
-
-__Sentence Structure. __ To some extent, sentence structure issues are discussed in the grammar section; however, there are some additional issues
-that are not grammatically incorrect but do interfere with the readers comprehension of the material. One of the most noticable of these
-is stacked prepositional phrases. Stacked prepositional phrases become a problem when the document's readability suffers
-because it becomes less and less clear what the subject and action of the sentence are. In some cases more
-precise descriptors are needed or sentences need to be changed from one long sentence that is hard to
-comprehend, to two or three more easily read sentences.
-
-
-*
-*
-
-__Readability. __ This area is somewhat subjective. What passes for fairly readable material to one person might be confusing to someone
-else. Because this is a value judgement you should be cautious when marking up an author's work for readability.
-Realize when basing a judgement on readability that you might be dealing with preferences of style. At this point
-in time within the LDP, there is no set style or stylistic rules that authors need to follow. In evaluating readability
-you must consider whether or not the way the document is written truly interferes with the readers understanding
-of the information. If the answer you come up with is "No, but it doesn't sound like I think it should."
-then you should probably not re-write the text to make it sound better to you.
-
-
-*
-*
-
-__Versioning. __ Every document should have a version number, preferably in the form
-Major.Minor.Bugfix, where each section is an integer.
-Some authors use Alan Cox style versions (e.g., 1.4pre-3) and some include
-additional information (e.g., 1.3beta). This is acceptable but not encouraged.
-The most important thing is that we ''have'' a version
-number so we know which version we are dealing with! Once a document goes through review it should
-advance in minor or bugfix version number, depending on the amount of change introduced.
-
-
-*
-*
-
-__Title. __The title should be in proper title case. The general principle for this is that all words are
-capitalized in a title except prepositions and articles (an article will be capitalized if it is the
-first word in the title). The word HOWTO should be
-in all capital letters. There should be no hyphens within the word HOWTO (with the exception of the Mini-HOWTO).
-The version should not be included in the title.
-
-
-*
-*
-
-__Date Formats. __Dates should be in standard ISO format, which is YYYY-MM-DD.
-
-
-*
-*
-
-__Uniform Use of Terms. __ Because the HOWTO you are reviewing is probably filled with new information for the reader, it is important
-that the terms discussed throughout the document be uniform. For example, referring to a part or parameter in one section of the
-document by one name and then calling it by another name (or an abbreviation that has not be explained) in another
-part of the document is confusing for the reader. Making sure that terms are the same throughout the document
-goes a long way in helping the reader understand the documentation.
-
-
-*
-*
-
-__Definitions of Acronyms or Slang. __ Terminology and language within the realm of computer technology changes rapidly. In reviewing documents
-you may find that many of the terms that are being discussed are not valid words in any dictionary or technical
-reference that you are familiar with. In this case you will need to search on terms and find if they are, in fact,
-terminology that is accepted in the general Linux community. Terms that are less familiar should be defined immediately
-following the first instance of the term. Slang should be replaced with more common terminology if the slang will
-causes the reader to be confused by the connotation or denotation of the term. Remember that readers using
-the document may not come to English as a primary language and, therefore, you should do your best to make sure
-that the document is as easy to understand as possible.
-
-
-*----
-!!!6. Reporting Your Results
-
-Once you have completed your review of a document, you should send your results back
-to the working group. The coordinator will record your work in the database.
-The coordinator will not need the updated source, but he or she will need any metrics
-you have collected and your notes. He or she will also need to know which types of review
-you have completed.
-
-
-
-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
-''submit@linuxdoc.org''
.
+Describe [HowToLDPReviewerHOWTO]
here.
