394 lines
12 KiB
HTML
394 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Language Review</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="Linux Documentation Project Reviewer HOWTO"
|
|
HREF="index.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Technical Accuracy Review"
|
|
HREF="techreview.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Metadata and Markup Review"
|
|
HREF="metadatareview.html"></HEAD
|
|
><BODY
|
|
CLASS="sect1"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Linux Documentation Project Reviewer HOWTO</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="techreview.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="metadatareview.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="languagereview"
|
|
></A
|
|
>6. Language Review</H1
|
|
><P
|
|
>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.
|
|
</P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>Items to evaluate:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Spelling. </B
|
|
> Spelling should conform to a standardized English spelling of terms. For words that are new
|
|
to the language and not yet standardized (for example technical Linux terminology that is generally accepted
|
|
in the community), follow the most common spelling for the term.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
>Note</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>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
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"realise"</SPAN
|
|
> you should not change the spelling of
|
|
the word to <SPAN
|
|
CLASS="QUOTE"
|
|
>"realize"</SPAN
|
|
> just because you speak/write American English.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Grammar. </B
|
|
> 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. </P
|
|
></DIV
|
|
><P
|
|
>For example, to say, <SPAN
|
|
CLASS="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."</SPAN
|
|
> 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 <SPAN
|
|
CLASS="QUOTE"
|
|
>"The ones"</SPAN
|
|
> refers to the parameters.</P
|
|
><P
|
|
>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.</P
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Use of capital letters. </B
|
|
>The word <SPAN
|
|
CLASS="QUOTE"
|
|
>"HOWTO"</SPAN
|
|
> should always be in full caps with no hyphen.
|
|
The document's title and section headings may follow one of two
|
|
conventions, but must be consistent throughout. Titles may either
|
|
capitalize only the first word, or may capitalize each word. In the
|
|
second case the only words not capitalized in a title are prepositions, articles,
|
|
and proper nouns which would not be capitalized otherwise (for
|
|
example: insmod). Other capitalization should follow rules of standard English.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Clarity. </B
|
|
> Judgements on clarity are sometimes difficult to make. One successful strategy in
|
|
evaluating clarity is asking the question <SPAN
|
|
CLASS="QUOTE"
|
|
>"If I did not already know this information, would
|
|
the explanation be clear from this document."</SPAN
|
|
> 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. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Organization. </B
|
|
> 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.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Sentence Structure. </B
|
|
> 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 noticeable 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. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Readability. </B
|
|
> 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 <SPAN
|
|
CLASS="QUOTE"
|
|
>"No, but it doesn't sound like I think it should."</SPAN
|
|
>
|
|
then you should probably not re-write the text to make it sound better to you. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Title. </B
|
|
>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.
|
|
The version should not be included in the title.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Date Formats. </B
|
|
>Dates should be in standard ISO format, which is YYYY-MM-DD.</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Uniform Use of Terms. </B
|
|
> 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. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Definitions of Acronyms or Slang. </B
|
|
> 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. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Latin abbreviations. </B
|
|
>Avoid using abbreviations. e.g. (for example), et al. (and
|
|
others), etc (and so on) and i.e. (that is) should
|
|
always use the English equivalent.</P
|
|
></DIV
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="techreview.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="metadatareview.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Technical Accuracy Review</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Metadata and Markup Review</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |