Skip to content

Latest commit

 

History

History
129 lines (80 loc) · 3.67 KB

STYLE.adoc

File metadata and controls

129 lines (80 loc) · 3.67 KB

The Open Source Way Style Guide

Days, months, times, numbers

Rule Example

Abbreviate months with 6+ letters if used with a specific date.

Spell months with 5 or fewer letters. Do not use 1st, 2nd, 3rd, 4th, etc.

Jan. 1, Feb. 2, March 3, April 4, May 5, June 6, July 7, Aug. 8, Sept. 9, Oct. 10, Nov. 11, Dec. 12

Spell the month when used without a specific date.

In September, the leadership team…​

The session begins in February 2016.

Do not abbreviate days of the week.

Wednesday, June 1

For time, use numerals, a space, lowercase letters, and periods for a.m. and p.m.

* Do not use extra zeros on times.

* Specify time zone (include “D” if daylight savings is in effect).

* Include UTC time for global audiences.

7 p.m. EDT (11 p.m. UTC)

10:15 a.m. ET (3:15 p.m. UTC)

8 a.m.-2 p.m. 8-11 a.m.

Bookmark this time zone converter: http://tiny.cc/time-zone-converter

Spell out numbers under 10.

Use numerals for 10 and above, unless it’s the first word of the sentence.

There are five directors. No, wait, there are 15. Sixteen, now that I count them.

Punctuation

Rule Example

Always use the Oxford (serial) comma.

Apples, oranges, and bananas.

Avoid exclamation points.

No more than one per document.

Zero, if possible.

Avoid ampersands (&) or plus signs (+).

Use only if truly necessary to omit 2 extra characters, in which case, use plus sign.

Headlines and titles

Rule Example

Use sentence case capitalization for headlines, headings, subheadings, job titles, and most other situations. (Capitalize only first word, proper nouns, and first word after a colon or em-dash.)

Exceptions: Use “title case” for product, event, and award titles.

Pro-tips: http://tiny.cc/sentence-vs-title

Join us for a town hall on Super Project 1.0 with vice president Mike Smith

Favorite beverage of ALDP graduates: Milk

Happening today—The OpenStack Summit

Google named among Fortune’s Most Innovative Companies

Abbreviations and acronyms

Rule Example

Avoid acronyms. Spell out, unless it’s something that’s known primarily as an acronym.

HTML (not “HyperText Markup Language”)

Use 2-letter abbreviations for U.S. states.

Spell out countries (except when using “U.S.” as an adjective).

Austin, TX - See stateabbreviations.us

Brno, Czech Republic

In the United States vs. in U.S. history

That vs. which, plus tricky comma questions

Essential = no comma Nonessential = comma

I will give the document to my peer Chris.

(I have more than one peer. Chris’s name is essential info and should not be set off with a comma.)

I will give the document to my director, Kim.

(I have only one director. Her name is nonessential and thus set off with a comma.)

That

Which

John’s cars that are leased are never kept clean.

(The dirty cars are specifically those that John leased; John might have non-leased cars that are kept clean.)

John’s cars, which are leased, are never kept clean.

(All of John’s cars are dirty. The fact that those cars are leased is not essential to the meaning of the sentence.)

We visited Berlin too.

(“Too” is an adverb. When a sentence ends with an adverb that is essential to the meaning of the sentence, the adverb should not be set off with a comma.)

Mary Smith, a staff writer at the Big City Times, recently wrote a book on that subject.

(Nonessential information requires a comma.)