mirror of https://github.com/tLDP/LDP
This commit is contained in:
parent
0995772994
commit
0afad6d200
|
@ -1,341 +0,0 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
<article>
|
||||
<artheader>
|
||||
<title>Linux Documentation Project Reviewer HOWTO</title>
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<surname>Merrill</surname>
|
||||
<affiliation>
|
||||
<address><email>david@lupercalia.net</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Joy</firstname>
|
||||
<surname>Yokley</surname>
|
||||
<affiliation>
|
||||
<address><email>jyokley@us.ibm.com</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<pubdate>2001-05-12</pubdate>
|
||||
<abstract><para>This document will help you review LDP documentation.
|
||||
It includes procedures, tips and techniques to make the process easier.</para>
|
||||
</abstract>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.0.1</revnumber>
|
||||
<date>2001-05-12</date>
|
||||
<authorinitials>DCM</authorinitials>
|
||||
<revremark>Minor bugfixes.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>1.0</revnumber>
|
||||
<date>2001-05-01</date>
|
||||
<authorinitials>jy</authorinitials>
|
||||
<revremark>Initial release.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
</artheader>
|
||||
|
||||
<sect1 id="introduction"><title>Introduction</title>
|
||||
<para>The LDP Review Project is a "working group" of the
|
||||
<ulink url="http://www.linuxdoc.org"><citetitle>Linux Documentation Project</citetitle></ulink>
|
||||
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. </para>
|
||||
|
||||
<para>We have a mailing list established at
|
||||
<ulink url="http://www.lupercalia.net/mailman/listinfo/ldp-review">
|
||||
<citetitle>http://www.lupercalia.net/mailman/listinfo/ldp-review</citetitle></ulink>.</para>
|
||||
|
||||
<sect2 id="copyright"><title>Copyright and License</title>
|
||||
<para>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
|
||||
<ulink url="mailto:david@lupercalia.net"><citetitle>david@lupercalia.net</citetitle></ulink>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
</sect1>
|
||||
<sect1 id="newdocs"><title>Reviewing Newly Submitted Documentation</title>
|
||||
<para>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. </para>
|
||||
|
||||
<para>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. </para>
|
||||
|
||||
<para>
|
||||
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.</para>
|
||||
|
||||
<para>When reviewing newly submitted documents, refer to the <xref linkend="techreview"> and
|
||||
<xref linkend="languagereview"> 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.</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="existing"><title>Reviewing Existing Documentation</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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. </para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<sect2 id="picking"><title>Choosing a Document</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Notify the ldp-review list, which is currently housed at
|
||||
<ulink url="http://www.lupercalia.net/mailman/listinfo/ldp-review">
|
||||
<citetitle>http://www.lupercalia.net/mailman/listinfo/ldp-review</citetitle></ulink>,
|
||||
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.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="licenseissues"><title>License Issues</title>
|
||||
<para>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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="newversion"><title>Working With the Latest Version</title>
|
||||
|
||||
<para>Make sure the copy you are reviewing is the most current.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="pickatype"><Title>Picking a Review to Conduct</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
<sect1 id="techreview"><title>Technical Accuracy Review</title>
|
||||
|
||||
<para>Make sure the facts as stated in the document are correct, helpful, and on topic.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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. </para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="languagereview"><title>Language Review</title>
|
||||
|
||||
<para>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.
|
||||
</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Items to evaluate:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><formalpara><title>Spelling</title>
|
||||
<para> 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.</para>
|
||||
</formalpara>
|
||||
|
||||
<note><title>Note</title><para>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.</para></note>
|
||||
</listitem>
|
||||
|
||||
<listitem><formalpara><title>Grammar</title>
|
||||
<para> 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. </para>
|
||||
</formalpara>
|
||||
|
||||
<para>For example, to say, <quote>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.</quote> 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 <quote>The ones</quote> refers to the parameters.</para>
|
||||
|
||||
<para>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.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><formalpara><title>Capitalization</title>
|
||||
<para> The word <quote>HOWTO</quote> 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.</para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Clarity</title>
|
||||
<para> Judgements on clarity are sometimes difficult to make. One successful strategey in
|
||||
evaluating clarity is asking the question <quote>If I did not already know this information, would
|
||||
the explanation be clear from this document.</quote> 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. </para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Organization</title>
|
||||
<para> 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.</para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Sentence Structure</title>
|
||||
<para> 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. </para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Readability</title>
|
||||
<para> 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 <quote>No, but it doesn't sound like I think it should.</quote>
|
||||
then you should probably not re-write the text to make it sound better to you. </para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Versioning</title>
|
||||
<para> 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 <emphasis>have</emphasis> 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.</para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Title</title>
|
||||
<para>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.</para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Date Formats</title>
|
||||
<para>Dates should be in standard ISO format, which is YYYY-MM-DD.</para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Uniform Use of Terms</title>
|
||||
<para> 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. </para>
|
||||
</formalpara></listitem>
|
||||
|
||||
<listitem><formalpara><title>Definitions of Acronyms or Slang</title>
|
||||
<para> 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. </para>
|
||||
</formalpara></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="reporting"><title>Reporting Your Results</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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
|
||||
<ulink url="mailto:submit@linuxdoc.org"><citetitle>submit@linuxdoc.org</citetitle></ulink>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
Loading…
Reference in New Issue