6. Language ReviewBecause 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: | 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. |
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.
|
|