Style Guidelines

This whole page is based on the Ubuntu Magazine Style Guidelines. Kudos to them !

Presented here are style guidelines to keep in mind if you are editing or choose to submit text for publication to PostgreSQL Magazine.

Warning

If after submission your writing is chosen to be in the next issue of PostgreSQL Magazine, it will be subjected to proof-reading and editing. We respect authors' writing styles, but will change small details to fit the guidelines contained here. All revisions are in the spirit of constructive criticism and for the sake of consistency. Revisions could include things like changing awkward/weak words, moving paragraphs to achieve greater clarity, and removal/revision of redundant content, among other things. Don't be caught off-guard (or offended) by the editing of your work!

General rules

  • All articles must use American English spellings, for example: “flavor” (not the British “flavour”)
  • When documenting how to install software, avoid recommending a particular package manager (such as apt-get) - instead, simply use the phrase “Install package X from the Y repository.”
  • Remember that your writing is to be read, not spoken, so avoid excessive use of colloquialisms adopted from everyday use. This could confuse readers (especially if English is not their native language).
  • Use bullets for lists. Numbered lists are acceptable only when the order of each item is important.
  • If you are going to use sarcasm or irony make it clear. Include a confirmation that the statements are not actually serious. In print it can sometimes be unclear, and the obviousness is what gives sarcasm and irony bite.
  • No L33t spe4k! or smilies!
  • When quoting people, Nicola says, “The punctuation always goes inside the double quotes!”
  • Write out numbers one through twenty with words, 21+ with numbers. For ages, always use numbers, even if between one and twenty.
  • To minimize confusion between date conventions, write dates in the form, Month Day, Year. Months with more than five letters in their names will be abbreviated to Jan. Feb. March April May June July Aug. Sep. Oct. Nov. Dec.
  • Avoid using ordinal abbreviations (st, nd, rd and th).
  • When writing a list, use commas for each item, but not between the last two items. Example: I went to the store and bought apples, bananas, tomatoes and carrots.
  • We want to cultivate a friendly tone for the magazine. Do not be negative towards ideas or organizations that you may not agree with.

Punctuation

  • No space before a comma (:), a exclamation mark (!) and question mark (?). This one is very hard for French writers!
  • Please avoid dash (–), uses parentheses instead.

Common Pitfalls

INCORRECT CORRECT
Postgre, postgresql, pgsql PostgreSQL or Postgres
sql, Sql SQL
Pc, pc PC
Url, url URL
internet, net, 'net, web Internet
plugin, plug in plug-in
open-source, Open Source, OpenSource, Opensource open source

Scanability

For printed text, and even more so for computer/internet articles, scanability is crucial for a good reading experience. Articles should be focused, clear, concise and organized into logical paragraphs. By just reading four or five key phrases a reader should be able to get the gist of an article. Images and screenshots should match the text and support it, they should never just be added to take up space!

Passive voice

Use of the passive voice should be reserved for special cases. Why is this, you ask? Because a little use of the passive voice can go a long way to change the feeling of a piece of writing. FCM wants to cultivate a fresh, fun and casual tone of voice. Use of the passive form can make things sound dry, not-so-fresh, and static.