This section covers general guidelines.
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 #, where
nnnnis 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 #rather than as
mmmm, Bug #
(Bug #. (The word “Bug” preceding the number is important.)
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
Spell out numbers under 10, unless the same object appears in a sentence with an object 10 or over (five apples; 5 apples and 100 oranges).
Use numerals for versions (
Version 5), if it is an actual value (set
2), for bits (
32-bit), and for dates (
Phone numbers should appear in this format, using either spaces or dashes:
+49 30 82702940or
Ellipsis: The character entity for an ellipsis (…) causes problems when transforming a DocBook document to PDF output. Use the literal
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.
No period after list items unless one item forms a complete sentence (then use periods for all items within that list, even fragments).
Quotation marks: For which kind of quotation marks to use under which circumstances, see Section 4.7, “Quotes”.
In examples, only use URLs that are either owned by MySQL, or (preferably) URLs that are recommended for documentation in general:
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
--socketoption 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.