5.1 Guidelines on Grammar and Style

This section covers a number of common grammar and style issues.

Oracle Style Tips

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.

Some examples:

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...

Dealing with Keywords

Do not use contructs like this:

How to use SELECTs.

This is not just bad English, but makes it unnecessarily hard for translators. You could rewrite it like this:

How to use SELECT statements.

Another problem with constructs such as SELECTs is that it involves an ugly within-word font change. Constructs such as non-NULL do not have this problem because there is an intervening hyphen.

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.

Guidelines for Wording

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 its with it's. Rewrite it's as it is anyway, as part of the general rule to minimize apostrophes.

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 than 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.)

Punctuation Guidelines

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 it 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 n, not ASCII(n), unless you are referring to the ASCII() function, in which case you use <function>ASCII()</function> . For example, write ASCII 13.

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:

    • Precambrian

    • pre-Columbian

For a long dash, use &mdash;.

Comments: If a (comment) in 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, (Like this.).

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.