Style

Revision 15 as of 2007-06-19 17:30:10

Clear message

Full Circle Style Guidelines

Presented here are style guidelines to keep in mind if you are editing or choose to submit text for publication to Full Circle, the (unofficial) Ubuntu magazine. Note: If after submitting your writing your text is chosen to be in the next issue of the magazine, it will be subjected to proof-reading and editing. We respect your writing style, but will change small details to fit the guidelines contained here. All suggested revisions are in the spirit of constructive criticism. Suggestions on how to improve the work will be reviewed with the editor and the author. 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 guidelines

  • Ubuntu and derivative distros have their first letter capitalized, for example: Ubuntu, Kubuntu, not ubuntu, kubuntu.

  • Menu navigation shall be in the format Menu->Submenu->Submenu, for example: "From the menu, select File->Save. Not, click on File, then click Save as...

  • When documenting how to install software, try to avoid recommending a particular package manager (such as apt-get) - instead, simply use the phrase "Install package X from the Y repository". If appropriate, include a link to a page which documents the various package managers. (copied from WikiGuide/style)
  • Remember that your writing is to be read, not spoken, so avoid excessive use of colloquialisms adopted from everyday use, as it could confuse the reader (especially if English is not their native language).
  • If you are going to use a list, use bullets. 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 some kind of 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. Since you all are probably too dim-witted to understand what I'm talking about, I'm going to give an all-to-obvious example: "Read the previous sentence."

  • No L33t spe4k! Smile :) or smilies! Sad :(

  • When referencing or quoting another magazine, place the name of the publication in italics, with no underline. Capitalize each important word. Do not italicize "the" unless it is part of the masthead. So, a quote was pulled from the New York Times. Pablo reads The Economist. The writers of Full Circle Magazine are very consistent in their writing style! Books, radio, television, blogs, and other media are roman text and in quotes, again, with each important word capitalized.

  • When quoting people, Nicola says, "The punctuation 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. Example: There are ten group members. Their ages span between 19 and 25 years.
  • Avoid starting sentances with numbers. If absolutely necessary, spell out the number. for example: Nine billion people use Ubuntu Linux, even Mark Shuttleworth is surprised by this number
  • 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. Jan. Feb. March April May June July Aug. Sep. Oct. Nov. Dec. We are planning to party as if the date tonight were Dec. 31, 1999!

  • Avoid using st, nd, rd and th with numbers. Example: Mark Shuttleworth was the first African to fly in space. Not, Mark Shuttleworth was the 1st African in space. I can't believe Ubuntu was only sixteenth in the latest PC World list of 100 great products of 2007!

Specific words

Most acronyms will be written in all caps, thus a computer is a PC. An animation frequently found on the internet is a GIF, another picture is a JPG. Websites are generally written in HTML. A portable document is a PDF, and a web address is a URL. A CD is similar in shape to a DVD. Music files can be played in a variety of formats, including MP3, OGG and WAV. Movies can be viewed in MPG, WMV or sometimes AVG.

Disambigution

  • When you start your computer, you must log in (verb), which is different than a login (adj) window. The same rule applies to log out (v) and logout (adj).

  • Whether you are surfing the information super highway, streaming media, instant messaging, or doing anything else regarding the internet, you are online, never on line(with a space). Even when your computer is offline, it makes no sense for it to be off line (with a space).

  • When you have a cd, that is, a CD, that you would like to make a copy of you will have to rip onto your computer first, then burn it onto a new disc.

  • Burning a disk is a good way to lose all the files on your hard drive, burning a disc is a good way to back those files up.

  • Packaged with Ubuntu are many open source programs. They are not open-source.

  • A message sent over the internet is an email, never an e-mail.

  • A window that pops up is a pop-up, not to be confused with popup.

  • Memory now is now often measured in gigabytes, or GB, but in the past was more commonly measured in MB, and KB.

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. An example of passive voice is: "Rome (object) was founded by Romulus and Remus(subject)." The active voice would be: "Romulus and Remus(subject) founded Rome(object)." The difference is the subject; Is it acting or acting upon? In general (though this is not always the case), you can spot the passive voice from some form of the verbPC World "to be" (am, is, are, was, were, has been, have been, had been, will be, will have been, being) followed by a past participle (verb ending in -ed). Another example of a passive voice sentence is: "Questions on the Ubuntu forums are often answered by friendly people." A better choice may be the active voice (again, not always): "Friendly people often answer questions on the Ubuntu forums."

For more detailed information on the passive voice, and info on when it is a good idea to use it, the following sites are worth browsing:

More to come.