mariadb/Docs/ManualStyleGuidelines.wiki

OriginalAuthor: Paul DuBois

!!! ManualStyleGuidelines

''Version 1.1''

!! Revision History

* 2002-05-17 ArjenLentz - Version 1.0, Posted to Wiki
* 2002-06-03 ArjenLentz - Version 1.1, updates.

!! MySQL Manual Style Guidelines

Paul DuBois <paul@snake.net>

The following list of guidelines contains items that I've been jotting
down over time as style questions have come up in relation to the
MySQL manual. I wouldn't say they're exactly "official", but they
do reflect current working practice. Arjen asked me to post this
on the list some time ago so that it can be discussed with a view
to adding it (or something like it) to the source tree. So here it is!

Present in the mysql-4.0 source tree: Docs/ManualStyleGuidelines.wiki


The manual is written in UK English, not American English. This means:

 colour, not color
 behaviour, not behavior
 authorise, not authorize
 optimise, not optimize
 etc.

Write MySQL, not @strong{MySQL} (the manual used to use the latter, but no
more).

Write Unix, not UNIX.

Use uppercase for SQL keywords, functions names, etc., when writing
SQL statement examples.

To write a list of items, add commas after all items preceding the last one:
 Correct: Features, products, and services
 Incorrect: Features, products and services

How to pluralize keywords that are enclosed in @code:
 Correct: @code{SELECT}s
 Incorrect: @code{SELECTs} or @code{SELECT}'s or @code{SELECT}:s

Use "its" and "it's" correctly. These words are exceptions to
the normal use of "'s" to indicate possession:

it's = it is (e.g., "one of the strengths of MySQL is that it's fast")
its = possession (e.g., "MySQL is fast, which is one of its strengths")

"a lot" is two words. "alot" is rebarbative.

Write lowercase, not lower case

Write uppercase, not upper case

Write lettercase, not letter case

Write "web site" (two words), not "website", and "web page" rather
than "webpage".

The word "data" is problematic. It's 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's unfortunate that no matter which form we use, it
will look incorrect to some people. But we can at least be internally
consistent.
(Paul: I think that the O'Reilly proofread might have caught one or two of these; could you please pick up on these but don't change them back straight away until the book is finished? Thanks; Arjen).

Write "press Enter", not "hit Return" or "hit Enter".

When reproducing program output, reproduce it exactly, even if it contains
typos. Don't "fix" it. (If the output is produced by a MySQL program, then
fix the source for the program to write the output correctly without the
typo, then update the manual to match.)

Use "okay" rather than "ok" or "Ok" or "OK" in sentences. Exceptions:
* When describing instructions for a GUI with buttons that say "OK", then use "OK". That is, use the label that the GUI uses.
* When showing the output from a program, show the output exactly; don't change "ok" to "okay", etc.

Write "Open Source" (inside @code{}), not "open source".

To put something in quotes, do it ``like this,'' not "like this"
or 'like this.' In the latter two cases, the quotes will come
out looking rotten in printed formats.
Exception: quotes in code examples should be written using whatever
contention the program language requires.

Table types should be written using @code{}; write @code{MyISAM}, not
MyISAM.

When possible, use table names that are singular, not plural.
For example, use "item" rather than "items", or "person" rather than
"people". Sometimes you can add "_list" (as in "item_list") to make it
more clear that the name refers to a collection of items.

 Some commonly occurring misspelling:

 Correct         Incorrect
 ---------------------------
 publicly        publically
 statically      staticly
 dynamically     dynamicly
 automatically   automaticly

There is no hyphen after "ly" words. Write statically linked, not
statically-linked.

To refer to ASCII codes, use ASCII n, not ASCII(n), unless you're
referring to the ASCII() function, which case you use @code{ASCII()}.

 ASCII 13             indicates ASCII character code 13
 @code{ASCII(13)}     indicates a function call

backup is a noun or adjective (as in "a backup file"), back up is a verb
(as in "to back up a database")
rollback is a noun or adjective (as in "a rollback operation"), roll back
is a verb (as in "roll back a transaction")

core dump is a noun or a verb (as in "a core dump file" or "a program
core dumps when it fails"). In the latter case, however, it's better say
say "a program dumps core when it fails").

Write character set names in @code{}, e.g., @code{latin1}, @code{win1251}.

To prevent problems with various output formats, there should be no link
titles in a @uref{}. So @uref{url} is allowed, @uref{url,blabla} is not.
 Use this format:
		@uref{url} (WWW)
 Not this format:
		@uref{url, WWW}
 Similarly for FTP sites.

URLs ending in a domain name or directory should have a "/" at the end.
(For example, the URLs for all mirror sites should be written that way.)

Privilege names are written using @strong and lowercase, as in "the
@strong{process} privilege". Column names in the grant tables are
written using @code and the lettercase found in the table definition,
as in "the @code{Process_priv} column".

Write "e-mail", not "email". Exceptions are the @email{} construct, and
the Email attribute name in X509 certificate strings.

Write thread-safe, transaction-safe, replication-safe, not thread safe,
transaction safe, replication safe.

Write wildcard, not wild card or wild-card.

Use "indexes", not "indices": Adding indexes to a table will improve the
performance of SELECT statements.
Exception: when returning to array elements, use "indices": The elements
of the array may be accessed using numeric indices, where the index
values ranges from 0 to n.

Write "heavy-load production systems" (used as an adjective),
but "...used under heavy load" (used on its own).

Write PostScript, not Postscript.

When writing a list like "A, B, and C", include a comma before the last and.

Write case-sensitive and case-insensitive (hyphenated).

Write runtime, not run time.

Write backward-compatible, not backward compatible or backwards compatible.

Write application-related, not application related.

Write filesystem, not file system.

Write file-size, not file size.

Write datafile, not data file.

Write power-start, not power start.

Write percent, not per cent.

Write "toward", "and onward", not "towards", "onwards".

Write third-party, not third party.

Write turnkey, not turn-key.

Write "the Net" (capitalised) if referring to the Internet in that way.

Write long-awaited, not long awaited.

Write natural-language, not natural language.

Write low-volume <something> (when used as an adjective).

Write platform-dependent, not platform dependent.

Write something like "mentioned previously" instead of "above", and "later in this section" instead of "below" when making such relative references in your text.

Write "... shown here", not "... shown below".

Write "following some", not "something [shown] below".

Write high-priority <something> (when used as an adjective), not high priority.

Write "whether", not "whether or not".

Write hand-held, not hand held.

Write rewriting, not re-writing.

Write re-issue(ing), not reissue(ing).

Write command-line, not command line.

Write server-side, not server side.

Write "<blabla> only", not "only <blabla>".

Write floating-point, not floating point.

Write heavy-duty, not heavy duty.

Write online, not on-line.

Write user-defined, not user defined.

Write multi-user, not multi user.

Write multi-thread(ed), not multithread(ed).

Write memory-based, not memory based.

Write long-time <something> (when used as an adjective), not long time.

Write 32-bit, not 32 bit or 32 bits. (Same goes for 64-bit, of course! ;-)

Write "different from [what] ...", not "different than ...".

Write "@-e.g., " instead of " e.g. " in the middle of a sentence. (The @- will be turned into a dash, or &mdash; for DocBook output.)
Following "e.g." by a comma, not a space or a colon.

Write "@-" if you need to put a dash in a text, no surrounding spaces.

Similar story for "for example" as for "e.g."

Write CPU, not cpu (it's an acronym, not a word! ;-)

Write "... uses ... CPU time", not "... uses ... CPU" (unless you're referring the processor itself.)

If a (comment) is at the end of a sentence, start the comment with lowercase and put the . after the closing ), such as (like this).
If a comment is separate, start with uppercase and put the . inside the closing ). (Like this.)

Write "something cannot do something", not "something can not something".

Write "otherwise, ..." (with the comma) at the start of a sentence.

Paul, could you please check "honoring"... is this proper British English? Thanks, Arjen.

Write "byte-swapping", not "byte swapping".

Write "Note:", not "NOTE:". And then continue with lowercase, it is not the start of a new sentence.

Write "single-CPU" and "multiple-CPU", not "single CPU" and "multiple CPU".

Paul, I think we should also decide whether to write Version or version, and in what situation. I am not changing much now because there's lots of funny instances and I don't want to risk getting it wrong. Thanks, Arjen.

After a semicolon, don't use uppercase. It is NOT the start of a new sentence!

It's "unstable", not "instable". ;-)

It's "full-text", not "fulltext".

Logical NOT/OR/AND are operators, not functions, so they take operands, not arguments.

It's NetWare, not Netware (as per Novell's trademark guidelines).

It's deprecated, not depricated.