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.
Paul DuBois <paul@snake.net></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.
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></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></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></blabla> only", not "only <blabla></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></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 — 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.