Acronyms should generally be spelled out the first time they appear in a book, as in: “Computer Development Environment (CDE).” After the acronym has been defined, you should generally use the acronym only (not the whole term, unless it makes more sense contextually to use the whole term). Usually, acronyms are defined only one per book. But if you prefer, you can also define them the first time they appear in each chapter.

Change notes: In change notes, references to bug numbers should be written after the sentence describing the bugfix, like this: This sentence describes the fix. (Bug#nnnn), where nnnn is the number of the bug assigned in the MySQL bug tracking system. The process that converts the Manual to HTML finds these and transforms them to hyperlinks that take the reader to the proper report in the bug system at http://bugs.mysql.com.

If there are multiple bugs, write them as (Bug #mmmm, Bug #nnnn) rather than as (Bug#mmmm, #nnnn). (The word “Bug” preceding the number is important.)

Code lines should run no longer than 72 characters. This is particularly important for printed books. Code lines should be indented using spaces, not tabs.

Commas: To write a list of items, add commas after all items preceding the last one. Example: Features, products, and services, not Features, products and services

Dates and numbers:

Ellipsis: The character entity for an ellipsis (…) causes problems when transforming a DocBook document to PDF output. Use the literal ... instead.

Footnotes: Do not use footnotes at all. Footnotes work well for print or PDF, but we use our documentation in many other formats such as HTML, where footnotes require a lot of navigation on the reader's part. It can take some thought to determine how best to incorporate into a passage the text that you might otherwise put in a footnote. Make the effort. Sometimes in doing so you will become aware that you were using a footnote as a means of being lazy, and that having to rethink a passage reveals a much better way of organizing what you are trying to say.

Language: US English, not UK English. (optimize, not optimise; center, not centre; color, not colour; transportation, not transport; etc.)

Lists: We use two types of lists only: numbered lists and bulleted lists. For the former, use the <orderedlist>, for the latter, use the <itemizedlist> element.

No period after list items unless one item forms a complete sentence (then use periods for all items within that list, even fragments).

Quotes: For which kind of quotes to use under which circumstances, see Section 4.7, “Quotes”.

Spaces, not tabs: Do not use tab characters at all, use spaces instead.

URLs are considered breakable at punctuation characters. This is how Pearson handles it in printed materials.

In examples, only use URLs that are either owned by MySQL, or (preferably) URLs that are recommended for documentation in general:

Example:

You have reached this web page by typing “example.com”,
“example.net”, or “example.org” into the
address bar of your web browser.

These domain names are reserved for use in documentation and are not available for registration. See RFC 2606, Section 3.

We recommend using binary distributions, rather than source distributions.

If a section contains instructions for both types of distributions, put those for binary distributions first. If you find a section that still has source instructions first, see if it can be rewritten to put binary instructions first.

We now have more Windows users than Unix users. So, if a section contains instructions for both platforms, put those for Windows first, then Unix. If you find a section that still has the Unix instructions first, see if it can be rewritten to put Windows first.

Example of allowable exception: The --socket option is used for specifying a Unix domain socket file name or a Windows named pipe name. The name of the option itself obviously has its roots in the Unix usage, so it can make sense to mention its Unix meaning first and then the Windows meaning. Such exceptions tend to be rare.