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

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.

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.

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.

Make sure you do not confuse its with it's. This can best be accomplished by following the next rule.

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.

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

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:

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

For a long dash, use —.

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.