LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

Minor updates to the language and markup, emphasizing the 

reporting procedures for reviews. Also changed the order of the reviews
	to reflect actual procedure (technical, language and finally metadata).
This commit is contained in:
emmajane 2004-04-19 23:18:15 +00:00
parent da0741a05b
commit 7f95f57d7f
1 changed files with 166 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

282
LDP/howto/docbook/LDP-Reviewer-HOWTO.xml
View File

@ -24,12 +24,22 @@
<address><email>jyokley@us.ibm.com</email></address>
</affiliation>
</author>
<pubdate>2004-04-18</pubdate>
<pubdate>2004-04-19</pubdate>
<abstract><para>This document will help you review LDP documentation.
It includes procedures, tips and techniques to make the process easier.</para>
It includes procedures and techniques for the review process
of all new, and existing, LDP documents.</para>
</abstract>
<revhistory>
<revision>
<revnumber>1.4.1</revnumber>
<date>2004-04-19</date>
<authorinitials>EJH</authorinitials>
<revremark>Minor updates to the language and markup, emphasizing the
reporting procedures for reviews. Also changed the order of the reviews
to reflect actual procedure (technical, language and finally metadata).</revremark>
</revision>
<revision>
<revnumber>1.4</revnumber>
<date>2004-04-18</date>
@ -68,12 +78,11 @@
</articleinfo>
<sect1 id="introduction"><title>Introduction</title>
<para>The LDP Review Project is a &quot;working group&quot; of the
<para>The LDP Review Project is a <quote>working group</quote> of the
<ulink url="http://www.tldp.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>
We are open to your suggestions for improvement. </para>
<para>We have a mailing list established for editors; instructions to subscribe are at
<ulink url="http://www.tldp.org/mailinfo.html#maillists">
@ -93,11 +102,12 @@
Joy Yokley and David C. Merrill, Ph.D.. Tabatha Marshall updated the
content and converted the document to DocBook XML in November 2003.
Emma Jane Hogbin added the section on Metadata and Markup Reviews in
January 2004.</para>
January 2004 and is the current maintainer of the document.</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
@ -113,7 +123,7 @@
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>
to be conducted 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.
@ -124,9 +134,13 @@
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>
coordinator and let them know what the problems are. Once changes are made, the reviewer will update the minor
version number, add a new entry to the revision history, and include
their name as an <quote>editor</quote> of the document. These
changes will then be submitted to the CVS, and an original copy will
be sent to the author of the document if the author does not have
CVS access.
</para>
</sect1>
@ -143,13 +157,12 @@ and make any necessary changes. If changes are
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
<para>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>
@ -175,7 +188,8 @@ and make any necessary changes. If changes are
Of course, it is still polite, and advisable, to write the author anyway.</para>
<para>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.
author to choose and apply one. More information on licensing is
available in <xref linkend="metadatareview" />
</para>
</sect2>
@ -210,101 +224,6 @@ and make any necessary changes. If changes are
<para>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 (<ulink url="www.tldp.org/mailinfo.html#maillists" />).</para>
</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>
<para>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.</para>
</sect1>
<sect1 id="metadatareview"><title>Metadata and Markup Review</title>
<para>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.</para>
<sect2 id="requiredmarkup"><title>Required Markup</title>
<para>Documents submitted to TLDP document repository must validate as one of the following:</para>
<itemizedlist>
<listitem>
<para>
DocBook XML version 4.2 (preferred), 4.1.2
</para>
</listitem>
<listitem>
<para>
DocBook SGML version 4.2, 4.1 or 3.x
</para>
</listitem>
<listitem>
<para>
LinuxDoc SGML
</para>
</listitem>
</itemizedlist>
<para>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.</para>
</sect2>
<sect2 id="requiredmetadata"><title>Required Metadata</title>
<para>The following elements are all required:</para>
<itemizedlist>
<listitem><formalpara><title><sgmltag>articleinfo</sgmltag> or <sgmltag>bookinfo</sgmltag></title>
<para>If you are writing a shorter HOWTO (this will be most documents) you will need to use an <sgmltag>articleinfo</sgmltag>, if you are writing a longer guide you will need to use <sgmltag>bookinfo</sgmltag>.</para></formalpara>
</listitem>
<listitem><formalpara><title><sgmltag>title</sgmltag></title>
<para>Every document must contain a short, descriptive title. It should be reasonably unique; check other documents in the collection to make sure your document's title is distinctive from all other documents. Although it is not required, most <quote>HOWTO</quote> documents contain the word <quote>HOWTO</quote> in the title.</para></formalpara>
</listitem>
<listitem><formalpara><title><sgmltag>abstract</sgmltag></title>
<para>A short description of your document must be included in the <sgmltag>abstract</sgmltag>. This description is typically one or two sentences in length.
</para></formalpara>
</listitem>
<listitem>
<formalpara><title><sgmltag>author</sgmltag></title>
<para>Every document must have an author. If there are multiple authors, you may use <sgmltag>authorgroup</sgmltag>. If the document was prepared by an organization with no individual author, please use <sgmltag>authorcorp</sgmltag> instead.</para></formalpara>
</listitem>
<listitem>
<formalpara><title><sgmltag>pubdate</sgmltag></title>
<para>The date of publication for the document. The date should be in the ISO standard of YYYY-MM-DD.</para></formalpara></listitem>
<listitem><formalpara><title>copyright</title>
<para>Authors will always retain the copyright to any documents they submit to the LDP. Although it is not required, a copyright notice may be included. A license, however, is always required.</para></formalpara>
</listitem>
<listitem><formalpara><title>Revision history (<sgmltag>revhistory</sgmltag>)</title>
<para>A summary of revisions should be included in the document. For more information about their markup, please read the notes in the <citetitle>Author Guide</citetitle>'s <ulink url="http://tldp.org/LDP/LDP-Author-Guide/html/metadata-markup.html">Markup for Metadata</ulink>.</para></formalpara>
<para>The initial release of a document should be marked up as Version 1.0. Subsequent updates should increment the version number appropriately. The preferred format is Major.Minor.Bugfix, where each section is an integer.
Some authors use Alan Cox style versions (for example 1.4pre-3) and some include
additional information (for example 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>
</listitem>
<listitem><formalpara><title>License and Legal Notice</title>
<para>A license is required. The LDP currently accepts documents which are licensed under the GFDL, Creative Commons License and the LDP License. If you are using a license that is not listed it will need to be reviewed by our volunteers before the document is accepted. The full text of the license is required. A link is not sufficient. You may wish to include a disclaimer as part of the legal notice. A standard disclaimer is available from the <citetitle>Author Guide</citetitle>.</para></formalpara>
</listitem>
<listitem>
<formalpara><title>email</title>
<para>The LDP must be able to reach any author of any document via email. Email addresses should be included in the <sgmltag>author</sgmltag> tag, but may be included in the DocBook source as a comment. Documents without email address will not be accepted into the collection. If the LDP is unable to reach an author, the document may be removed from the collection.</para></formalpara>
</listitem>
<listitem><formalpara><title>Acknowledgements and Other Credits</title>
<para>Very few, if any, documents are written only by one person. It is good form to thank those who helped you with either the writing, research, testing or reviewing of your document. If someone added markup, or translated your document to another language they should also be given credit.</para></formalpara>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="languagereview"><title>Language Review</title>
<para>Because writers come from all types of backgrounds, there may be problems
@ -340,8 +259,9 @@ and make any necessary changes. If changes are
<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 &quot;realise&quot;, you should not change the spelling of
the word to &quot;realize&quot; just because you speak/write American English.</para></note>
author is writes British English and uses the word
<quote>realise</quote> you should not change the spelling of
the word to <quote>realize</quote> just because you speak/write American English.</para></note>
</listitem>
<listitem><formalpara><title>Grammar</title>
@ -450,8 +370,131 @@ and make any necessary changes. If changes are
</itemizedlist>
</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>
<para>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.</para>
</sect1>
<sect1 id="metadatareview"><title>Metadata and Markup Review</title>
<para>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.</para>
<para>At this time Metadata and Markup Reviews will be conducted by
one of the Review Coordinators and will be the final of the three
reviews for new documents. Upon successful completion of a Metadata
and Markup Review, the Review Coordinator will update the document's
version number to 1.0 and submit the document for publication in the
collection.</para>
<sect2 id="requiredmarkup"><title>Required Markup</title>
<para>Documents submitted to TLDP document repository must validate as one of the following:</para>
<itemizedlist>
<listitem>
<para>
DocBook XML version 4.2 (preferred), 4.1.2
</para>
</listitem>
<listitem>
<para>
DocBook SGML version 4.2, 4.1 or 3.x
</para>
</listitem>
<listitem>
<para>
LinuxDoc SGML
</para>
</listitem>
</itemizedlist>
<warning><title>Authors are not required to submit documents in DocBook</title>
<para>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.</para></warning>
</sect2>
<sect2 id="requiredmetadata"><title>Required Metadata</title>
<para>The following elements are all required:</para>
<itemizedlist>
<listitem><formalpara><title><sgmltag>articleinfo</sgmltag> or <sgmltag>bookinfo</sgmltag></title>
<para>If you are writing a shorter HOWTO (this will be most documents) you will need to use an <sgmltag>articleinfo</sgmltag>, if you are writing a longer guide you will need to use <sgmltag>bookinfo</sgmltag>.</para></formalpara>
</listitem>
<listitem><formalpara><title><sgmltag>title</sgmltag></title>
<para>Every document must contain a short, descriptive title. It should be reasonably unique; check other documents in the collection to make sure your document's title is distinctive from all other documents. Although it is not required, most <quote>HOWTO</quote> documents contain the word <quote>HOWTO</quote> in the title.</para></formalpara>
</listitem>
<listitem><formalpara><title><sgmltag>abstract</sgmltag></title>
<para>A short description of your document must be included in the <sgmltag>abstract</sgmltag>. This description is typically one or two sentences in length.
</para></formalpara>
</listitem>
<listitem>
<formalpara><title><sgmltag>author</sgmltag></title>
<para>Every document must have an author. If there are multiple authors, you may use <sgmltag>authorgroup</sgmltag>. If the document was prepared by an organization with no individual author, please use <sgmltag>authorcorp</sgmltag> instead.</para></formalpara>
</listitem>
<listitem>
<formalpara><title><sgmltag>editor</sgmltag></title>
<para>Every new document must go through the review process and have
a technical, language and metadata/markup review editor listed. In
some cases two of the reviews may have been conducted by the same
person. The name of the editor and the version their review was
conduct on should be included. For more information about this markup, please read the notes in the <citetitle>Author Guide</citetitle>'s <ulink url="http://tldp.org/LDP/LDP-Author-Guide/html/metadata-markup.html">Markup for Metadata</ulink>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara><title><sgmltag>pubdate</sgmltag></title>
<para>The date of publication for the document. The date should be in the ISO standard of YYYY-MM-DD.</para></formalpara></listitem>
<listitem><formalpara><title>copyright</title>
<para>Authors will always retain the copyright to any documents they submit to the LDP. Although it is not required, a copyright notice may be included. A license, however, is always required.</para></formalpara>
</listitem>
<listitem><formalpara><title>Revision history (<sgmltag>revhistory</sgmltag>)</title>
<para>A summary of revisions should be included in the document. For more information about their markup, please read the notes in the <citetitle>Author Guide</citetitle>'s <ulink url="http://tldp.org/LDP/LDP-Author-Guide/html/metadata-markup.html">Markup for Metadata</ulink>.</para></formalpara>
<para>The initial release of a document should be marked up as Version 1.0. Subsequent updates should increment the version number appropriately. The preferred format is Major.Minor.Bugfix, where each section is an integer.
Some authors use Alan Cox style versions (for example 1.4pre-3) and some include
additional information (for example 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>
</listitem>
<listitem><formalpara><title>License and Legal Notice</title>
<para>A license is required. The LDP currently accepts documents which are licensed under the GFDL, Creative Commons License and the LDP License. If you are using a license that is not listed it will need to be reviewed by our volunteers before the document is accepted. The full text of the license is required. A link is not sufficient. You may wish to include a disclaimer as part of the legal notice. A standard disclaimer is available from the <citetitle>Author Guide</citetitle>.</para></formalpara>
</listitem>
<listitem>
<formalpara><title>email</title>
<para>The LDP must be able to reach any author of any document via email. Email addresses should be included in the <sgmltag>author</sgmltag> tag, but may be included in the DocBook source as a comment. Documents without email address will not be accepted into the collection. If the LDP is unable to reach an author, the document may be removed from the collection.</para></formalpara>
</listitem>
<listitem><formalpara><title>Acknowledgements and Other Credits</title>
<para>Very few, if any, documents are written only by one person. It is good form to thank those who helped you with either the writing, research, testing or reviewing of your document. If someone added markup, or translated your document to another language they should also be given credit.</para></formalpara>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="reporting"><title>Reporting Your Results</title>
<para>Once you have completed your review of a document, you should send the updated file and your
@ -461,14 +504,17 @@ and make any necessary changes. If changes are
document management system is implemented, allowing for review notes to be stored with the file
in a database record.</para>
</footnote>
, 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.
, and advise the working group you've completed the review. A summary
of your findings should be included in the body of the email. If the
reviewer has access to the CVS, and permission of the author to submit
the changes directly, the reviewer may email the Review Coordinator
with only a summary of findings and a note that the document was
updated in the CVS.
</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
author or maintainer, as well as the LDP <emphasis>submission
list</emphasis>, which is at
<ulink
url="mailto:submit@en.tldp.org"><citetitle>submit@en.tldp.org</citetitle></ulink>.
The subject line should be the title of the document.
@ -476,6 +522,10 @@ and make any necessary changes. If changes are
to the effect of, <quote>I am a reviewer for the LDP and am submitting an
updated copy of this document on behalf of the author.</quote>
</para>
<note><para>
Updates should not be sent to the discuss list.
</para></note>
</sect1>