User:Tom Morris/Draft Style Guide

Here is a codifications of my own practice. You don't have to follow them, but if you want to be cool and smart and an all-round excellent person, you probably should.

There are two fundamental rules:

1. Stay consistent.
2. Follow common usage.

Citizendium articles shouldn't be self-referential

Don't say what an article "will present". In fact, don't talk about "this article". It should be obvious without further explication what an article will present because the article goes on to present it. A well-structured article does not need to refer to what it will do. You don't walk down the street and loudly inform everyone that you are walking down the street. This breaks article modularity also. A good article needs to have good flow, but also needs to be somewhat modular. One should be able to rejig an article's structure without needing to rewrite a great deal.

Abbreviations and acronyms

Consistency and following common usage is key here, but there are some practices which are fairly terrible and should be avoided. The BBC has a habit of making a huge number of acronyms capitalised in a rather undignified way:

• Home Information Packs should probably be abbreviated to a "HIP" or "HIPs", but the BBC have staretd using "Hips", which leads to hilarious headlines like "Hips extended to all properties" and Minister 'lost nerve' over hips
• The BBC write "police constable" as "Pc", not "PC", which becomes pluralised as "Pcs" (and "WPCs" - women police constables - becomes "Wpc", "Wpcs", "Wpc's", or even "WPc's"!). This looks tremendously odd and silly.
• It is "AIDS" (Aquired Immune Defiency Syndrome), not "Aids", despite what the BBC write. [1][2][3]
• It is an "ASBO" (Anti-Social Behavior Order), not an "Asbo".
• It is "ACAS", not "Acas" (Though ACAS themselves are guilty of this on their own website!)

See my blog post from August 2007 for explication of this idiotic trend.

Article naming

Now we have the 'abc' property in the metadata template, there is no more excuse for articles to be named in such a way as to affect their placement in A-Z listings. The 'curse of the comma' is to be avoided - we should prefer "History of American religion" to "American religion, history" - "Religion in the United States" would be the ideal title for such an article.

Similarly, the current name for World War II, Holocaust is dreadful - article names should not describe hierarchial relationships. The fact that the Holocaust happened during World War II can be explained in the article. When someone else sits down to write an article that mentions the Holocaust, will they find it easier to type "Holocaust" or "World War II, Holocaust". This kind of thing is absolute absurdity on a stick and should stop immediately.

We should not use the "comma, dreaded" in article names but either use bracketing for disambiguation - e.g. "Plato (philosopher)" - or use "of/in" syntax (as in "Religion in the United States" or "Computers in World War II". Excessive full stops look quite ugly in text, and look more so in article names. It makes you feel like you are reading the New York Times (N.Y.T.) who have this thing about putting full stops after everything, which makes it feel rather like the 1950s ("The British P.M. was sent an urgent telegram by the M.O.D. about possible U.S. attacks on the U.S.S.R."). The current way programming language articles are titled is also broken: Ruby programming language is not the name of the Ruby programming language. The first word is the name, the latter two words form a description. The description should be bracketed to form Ruby (programming language). Unfortunately, the Ruby programming language thing was something Wikipedia did but which has infected Citizendium also.

BCE and CE

You may think it's just jumped-up political correctness. I don't care. For us post-Christians, BCE and CE ("(Before) Common Era") make a lot more sense. They are being used widely in academia. Use them. It annoys the Conservapedia people too, which is fun. If you are that concerned about it, just mentally rewrite it as "(Before) Christian Era". If you think it is "trivial" (as some do), then why such big objections?

The actual year of birth of Jesus of Nazareth is disputed (as is his existence by some), whereas when the "Common Era" started has no such disputes. BCE/CE has also been widely adopted in academia, and we follow their lead. BCE/CE is also used by the Stanford Encyclopedia of Philosophy and the Internet Encyclopedia of Philosophy, the College Board, the United States Naval Observatory, the Jehovah's Witnesses, the Smithsonian and the History Channel.

Formatted dates

Dates ought to be formatted in such a way as to be readable internationally.

02-04-08. Simple enough, you say. The second of April 2008. Or is that the fourth of February 2008. Or maybe the eigth of April 2002. Or maybe it's 1908 rather than 2008.

Fortunately, the International Organization for Standards (or ISO) have solved this problem in ISO 8601. ISO 8601 forms the basis for a number of different date-time formats used on the Internet - it's used in the date-time format suggested by the W3C for XML, as part of the XML Schema Declaration Part 2: Datatypes standard. It's used in HTML 5. It's used in microformats. It's a very sensible date format. Why?

It's international and unambiguous. It can be composed or sliced into smaller or larger chunks.

• 2008-04-02 means the 2nd of April, 2008.
• 2008-04 means April, 2008.
• 2008 means what it says.

It does times too:

• 2008-04-02T05:24:36Z means 05:24:36 UTC (GMT-0)
• 2008-04-02T05:24:36-04:00 means GMT-4
• 2008-04-02T05:24:36+04:00 means GMT+4

Now, the sensible thing about ISO 8601 is that if you have a list of times as strings, they sort properly.

Unlike epoch-based times, you can specify ranges succintly: 2008-04 means all of April, 2008.

Now, ISO 8601 probably shouldn't be used in Citizendium. But the point about it is that learning the reasoning behind ISO 8601 prepares you for writing dates that are unambiguous.

British honors system and other funny naming quirks

• A Law Lord is a Lord, sits in the House of Lords, but does not exercise any legislative power, instead makes decisions on cases coming to the House of Lords in the judicial capacity. In legal articles, use "Lord Justice" in the body text, but use "LJ" in asides, boxes, templates, metadata etc.
• Knighthoods are for men, and they become "Sir". Damehoods are for women, and they become "Dame". Non-Brits who get knighthoods don't get referred to as Sir.
• A member of the House of Lords can be a Duke (or Duchess), a Count (or Countess), a Baron (or Baroness), a Viscount or a Marquis (or Marchioness). But in articles, they should probably be just Lord.
• Honors are great, but should be mentioned at the start of articles, then just use their name throughout.
• Article titles should not have honors. (Papal names are fine for articles though.)
• An honor is not "received", but you are appointed to that position. Do not talk of a person getting a CBE, but rather becoming a CBE.

Computers and the hackers who use them

Some people have screen names and usernames that are spelled weirdly. Follow the spelling given rather than attempting to normalize it. Hence, if you are referring to Tim Berners-Lee by his online nick, you write "timbl", not "Timbl" or "TimBL". Similarly, Unix utilities are all lower-case - it is "cat", not "Cat" or "CAT".

Probably not for use on Citizendium, but when reading hackers, be sure to remember that they like to intersperse some programming language syntax (much of which is equivalent to logical and mathematical symbols) into their English:

• "||" means 'or'
• ">" and "<" mean greater than and less than
• "s/foo/bar/" is derived from regular expressions and means "Substitute 'foo' with 'bar'."
• "~" means approximately - eg. "~100" means "approx. 100"

Numbering

• If something goes from 20% to 30%, it is a fifty percent increase, but is ten percentage points increase.
• Decimal, fraction or percentage: pick one.
• It is "1980s", not "1980's".

Quotes

If you are quoting someone, don't add punctuation to their quote. It looks silly. For instance:

"We are going to kick some ass in Iraq," said President Bush.

is wrong and should be written:

"We are going to kick some ass in Iraq", said President Bush.

The comma is not part of the quote, so don't insert it. This goes against standard American English practice, but that's because standard American English practice in this area is quite stupid and needs to change. It's especially bad in technical usage where the exact characters entered on a computer can be sensitive. See Hacker Writing Style by Eric Raymond for details.

Ugliness

The following usage is irredemably ugly and should stop immediately:

• "general public", "motorist" and other attempts at defining characteristics
• overuse of the word "community" - say what they are (a group, society, church, mailing list, small group of nutters claiming to represent the community etc.)
• "at the end of the day" when used to talk about what will happen as events conclude, rather than what happens at the end of the actual day

Verbing

Avoid verbing words - or, rather, avoid turning nouns into verbs: to Google (and to Facebook, to MySpace, to Twitter, to Wikipedia etc.), to euthanize, to guest (substitute 'searched on Google', 'killed' or 'put to sleep' and 'appeared as a guest' or 'was a guest' etc.). Some of these are widely accepted: to finalize, publicize and so on. Follow usage conservatively, and do not allow this to become a commandment. Sometimes verbing is the lesser of two evils.

Images

• No clip art.
• Don't place an image that illustrates something utterly obvious. Even in this day of relatively fast Internet speeds, for many, bits are still sparse commodities. Images, as the cliche says, can be worth a thousand words. Ensure those words aren't just the word "duh" repeated a thousand times over.
• Know the difference between a caption and a description. "Woman loking at medicine box" is a description of the image, but the caption ought to be explain very briefly the relation of the image to the article. And if you can't think of a reason why the image is in the article, perhaps it shouldn't be. See above.