This section covers a number of common grammar and style issues.
From an Oracle perspective, some key issues are:
Since we are writing for an international audience, avoid constructions that could impede understanding. (From American baseball metaphors to over-formal academic language.)
Since we are describing what the software actually does, to an audience that either has it already or is eagerly awaiting it, use the present tense rather than future tense (for example, avoid "will"). Remove most instances of past tense too. ("If the server crashes, restart it" rather than "If the server has crashed, you will need to restart it.")
Since the documentation serves as a warranty, be clear on what we are asking people to do. Use imperative voice, not passive voice. Minimize verbiage about what people "need to", "want to", "wish to", "consider", "ensure", "make sure", "attempt", "should" do, or even "must" do. If they should do it, tell them to do it. If they must do it, tell them to do it. Everything we ask them to do comes with an implicit "Ensure...". If the choice is entirely up to them, use a construct like "To do X, Y". Especially avoid constructs that layer hesitation upon uncertainty; if someone "may want to consider" whether to do something, that's asking them to go through two rounds of decision-making.
These changes minimize the chances of someone (a) making a bad choice and having a problem, then (b) filing a bug because the instructions were too timid or convoluted.
There could be cases where "should" versus "must" is a significant distinction. In such cases, rather than rely on the reader to decode such a slight difference, add a little more detail to be explicit. ("If performance drops, do X", "To avoid a syntax error, do Y", and so on.)
Avoid passive voice, because it obscures whether we are asking the reader to do something, or stating that something will be done for them. If the product does something, reword the sentence to say so (without anthropomorphizing too much). If the reader has to do something, use imperative voice.
Since we are competing for the reader's limited attention span, and they might be hurrying to fix a problem or meet a deadline, cut excess words and use shorter constructs wherever possible.
Since much of the source material comes from academic-minded developers, be diligent in getting rid of passive voice.
Since much of the source material is written when the software is still under construction, be diligent in getting rid of future tense.
Since developers don't want to over-commit themselves in specs, be diligent in giving advice and stating the consequences of not taking that advice.
State things in a positive way: improving performance, avoiding problems, recovering from a crash. State the right thing to do and its positive consequences, rather than the wrong thing and its negative consequences. Be alert for double- or even triple-negatives. ("If you do not disable this option, the query will not be optimized.") Again, specs have a lot of this kind of language.
Negatives include not just the grammatical sense of "not", but also words with unpleasant connotations, such disable, terminate, error, failure, illegal, invalid, slow, and so on. These aren't forbidden words, we just emphasize the positive notions where practical, because negativity can be a real barrier to new and inexperienced users. In particular, readers for whom English is not the first language can have strong negative reactions to words such as "illegal", "invalid", and "terminate" because of the secondary meanings (arrest, sickness, death).
Avoid "However...", as it is often a signal of a mixed message that can be jarring to a reader: "Everything is fine. However, you are in danger. Still, the danger is minimal." To state an embarrassing limitation or rarely needed warning, make the context clear and consistent, rather than issuing a series of contradicting statements. Sometimes, the "however" is superfluous. "Although" or "because" can alert the reader that an assertion is usually but not always true. Instead of leading off with an assertion, turn it into an instruction to avoid the problem or confusing situation.
Avoid "wordy" tenses such as perfect and present perfect. If you "can choose to" do something, you can do it. If a product is "designed to" or "intended to" do something, the product does it. If a notification "has been" sent, then it is sent, or was sent if it's important to emphasize the past aspect. Any extra linguistic precision from using these formal tenses isn't likely to help English-as-second-language readers, and the wordiness contributes to general reader inattention.
You may wish to consider whether to set the XYZ option. => Decide whether to set the XYZ option. You may want to set the XYZ option. => Optionally, set the XYZ option. You should set the XYZ option. => Set the XYZ option. You must set the XYZ option. => Set the XYZ option. Ensure the XYZ option has been set. => Set the XYZ option. If you want to set the XYZ option... => To set the XYZ option... In order to set the XYZ option... => To set the XYZ option... If you do not want your server to crash, you must ensure that the XYZ option has been set. => To avoid a server crash, set the XYZ option. Make sure that the XYZ option has been set, otherwise the server will crash. => To avoid a server crash, set the XYZ option. If you do not set the XYZ option, your server might be unstable. => For improved server stability, set the XYZ option. The server is very reliable. However, it will crash if you do not have enough disk space. => Although the server is very reliable, ... => For maximum reliability, leave at least 5 GB of free disk space to hold temporary files. Th advisors have been designed to identify issues... => The advisors identify issues...
Do not use contructs like this:
How to use SELECTs.
Under no circumstance allow instance of things like “SELECT's” or “SELECT:s” to go unchanged whenever you encounter them. Writing “SELECT's” is incorrect because it is not a possessive. Writing “SELECT:s” just looks weird. You are most likely to see these things in the Change Notes sections of the Reference Manual, because developers tend to be sloppier in their language there for some reason. As documenters, we have no such luxury. It is required that we expend the thought necessary to figure out how to rewrite the text properly.
Avoid expletives such as “simple”, “easy”, or “just”. Leave it to the reader or user to decide, for example, whether or not something is simple. Here's an example how to not write a sentence:
Using this feature is easy; simply click the red button.
Avoid terms that imply spatial direction when you really mean preceding or following. Use “mentioned previously” instead of “above” when making relative references in your text. Something that is “above” in a single-page presentation format such as a Web page will not necessarily be above in a multiple-page format such as a printed book. Similarly, use “later in this section” instead of “below.”
Do not confuse
it is anyway, as part of the general rule to
The word data is problematic. It is commonly
used both in plural and in singular form. The Manual uses it as
plural, which means you use
data are rather
data is. It is unfortunate that no matter
which form we use, it will look incorrect to some people. But we
can at least be internally consistent. If you can substitute
another word such as “information,” that makes the
problem go away entirely. “Metadata” is especially
problematic; there is a shortage of good synonyms. Sometimes you
can rewrite a sentence to avoid the singluar/plural issue
entirely. “The data are stored in the table” and
“The data is stored in the table” can be rewritten as
“The table stores the data.” (This also has the
benefit of changing the sentence from passive to active.)
Do not use emoticons such as :-), ;-), etc.
Do not end sentences with an exclamation mark (!). There can be exceptions, but they are rare. On occasion you might come across a passage consisting of three or four sentences in a row that end with exclamation marks. Invariably, you can change most of these to periods with no damage to the meaning, and the passage no longer will look like it's hyperventilating.
Apostrophes: Avoid using apostrophes. Print
publishers don't (uh, do not) like them. Write
is, rather than
it's. Note that this
rule may change due to an editor's preference.
Abbreviations: Avoid using abbreviations. They don't comply with the Sun Editorial Style Guide, and print publishers do not like them, either. Write “and so forth”, rather than “etc.”. Use “that is” and “for example”, rather than “i.e.” or “e.g.” If you absolutely must use i.e. or e.g., do not use i.e, ie, e.g, or eg.
When reproducing program output, reproduce it exactly, even if it contains typos. Do not “fix” it. (If the output is produced by a MySQL program, then fix the source for the program to the output correctly without the typo, then update the Manual to match.)
To refer to ASCII codes, use
ASCII(, unless you
are referring to the
ASCII() function, in
which case you use
. For example, write
The rules for hyphenated words are:
Use a hyphen for a combination adjective preceding its noun as in “case-sensitive collation”.
Do not use a hyphen for a combination adjective following a noun as in “this collation is case sensitive”.
Do not use a hyphen for a combination noun as in “case sensitivity”.
There is no hyphen after words ending with “ly”, for example “statically linked”, not “statically-linked”.
Do not use hyphens (or spaces) for prefixes such as “sub”, “pre”, or “re”, unless this is necessary to disambiguate words. For example, it's “subroutine”, “preamble”, or “reorder”, rather than “sub routine”, “pre-amble”, or “re-order”.
To disambiguate words, though, some people use hyphens, for example to disambiguate “recreation” (leisure) from “re-creation” (creating something anew). Others use hyphens when the stem of a word begins with a vowel. For example, they would use “re-introduced”, rather than “reintroduced”.
The usage of hyphens may depend on how naturalized a word is in English, and (this is related) to what extent it's regarded a proper noun. Here are some examples:
For a long dash, use
Comments: If a
parentheses is at the end of a sentence, start the
comment with lowercase and put the period (
after the closing parens (
)), such as
(like this).. If a comment is separate, start
with uppercase and put the period inside the closing parens,
After a semicolon, don't use uppercase. It is not the start of a new sentence.
After a colon, capitalize the next word if the following text is a complete sentence in itself. Do not capitalize if it is not a complete sentence.