Editorial Style Guide

This list is a constantly evolving collection of our house style decisions. Unless otherwise noted, see the Chicago Manual for questions on punctuation, capitalization, and grammar. See the word list for questions on word choice and spelling.

Images

Images should be no more than 696px wide; all images will be centered within the main column of the article.

If your images are high-DPI, please send both standard and high-DPI versions. For example, if you have a screenshot taken on a Retina device meant to be displayed at full-column width, please send one that is 696px wide, as well as one that is 1392px wide.

You can also use the code snippets image gist on Github.

PNG, GIF, and JPEG are all acceptable submission formats. GIF or PNG are preferred for images in which text features prominently. (Don’t use JPEG for a gallery of typefaces or a screenshot of a web page.) If you save as GIF, please choose the Perceptual, Selective, or Adaptive color spaces, No Dither, and No Transparency; matte against #fff (white). Please give us high-resolution images; we’ll compress as needed.

Author bios and photos

All final drafts should be accompanied by an author bio and photo. Author bios should
be 40 to 50 words long and may include links. They should be snappy, informative, and brief.

Examples:

Mat “Wilto” Marquis is a designer-slash-developer working at Filament Group in Boston. Mat is a member of the jQuery Mobile team, an active member of the open source community, and enjoys a complicated relationship with the HTML5 “dialog” tag. He’s probably flipping out about something on Twitter as we speak. (50 words)

Kevin Cornell is an illustrator/designer from Philadelphia, Pennsylvania. He spends the majority of his days maintaining his website, and drafting treaties for imaginary conflicts. It is rumored he is allergic to cashews, but that is largely unconfirmed. Kevin is the staff illustrator to A List Apart. (47 words)

Author photos don’t need to be professional portraits, but should look polished. A List Apart will prepare them for publication, so please send them as un-tweaked files with a minimum size of 400px by 400px.

Linking and metadata

Links

Choose link text that concisely indicates the nature of the linked document. Do not link terminal punctuation. Prefer shorter links to long ones.

Alt-attribute text

Accompany each illustrative image with alt-attribute text that concisely describes the image for those who cannot see it.

Examples:

Good: Illustration showing the overlap of divs A and B after floating div A.

Bad: Image showing example.

Alt-attribute text uses sentence-casing.

Title-attribute text

You may attach title text to some markup elements to convey additional information. Many web browsers display this information when the user’s cursor hovers over a link. A useful title attribute for an outbound link might read:

The results of PLAIN’s 2004 study on plain English in legal documents.

Title-attribute text uses sentence-casing.

Article titles, headlines, and subheads

Title case article titles (each major word is uppercase). Sentence case article headings (only the initial word is uppercase). Neither take terminal punctuation unless a question mark is required. Article titles do not take the serial comma and use the ampersand in place of “and.” Article headings do take the serial comma and use the word “and.”

Article title or document title:

Big, Stark & Chunky

Article header or subhead:

Big, stark, and chunky

Mark up article headings as h2 and subheads as h3 or h4 as needed. Most article headings are conceptually and rhetorically at the same level as each other; avoid unnecessary complexity and mark them up as h2 unless they’re true subheads. h1 is reserved for use as a page header.

Punctuation and capitalization

Acronyms and abbreviations: The acronym element is obsolete. Use abbr.

Ampersands: Do not use the ampersand except in article and page titles.

Citations: The titles of books and other major works as well as the titles of magazines and newspapers are marked up with the cite element. The titles of articles and other short works are enclosed in quotation marks.

Colons: Don’t capitalize the first word after a colon, unless it’s a proper noun/name or “I,” or the material preceding the colon is used as a subhead.

Commas: Use the serial comma (the comma preceding the “and” before the last element in a list) except in headlines, which should use the ampersand and no serial comma. Subheads use “and” and a serial comma.

Company and publication names: Capitalize the names of companies according to each company’s preference unless they begin a sentence, in which case they must be capitalized. Do not capitalize or otherwise emphasize the definite article before the name of a publication—even the New York Times.

Ellipses: Three periods together without spaces between. When used at the end of a sentence, include a single space after the ellipsis before the next sentence. When used in the middle of a sentence, do not include spaces between the words and the ellipsis.

Dashes: Use an em dash to set off a clause—like so. Do not leave a space on either side of the em dash. Use the en dash for enumerated date ranges only.

Hyphens: Hyphenate compound modifiers before a noun (“up-to-date code”). Keep open after the noun (“keep code up to date”). Don’t hyphenate when the first element is an adverb that ends in “ly.”

Lists:

  • If any item in a list (ordered or not) forms a complete sentence, all items must begin with a capital letter and end with a terminal punctuation mark.
  • If no items in an unordered list form a complete sentence, skip the capitalization and terminal punctuation.
  • If the items in the list complete an unfinished introductory sentence, end all but the last item with a semicolon, add an “and” before the final item, and finish off with terminal punctuation.

Quotation marks: Position punctuation according to Chicago rules (periods and commas go on the inside, colons and semi-colons go on the outside, question marks and exclamations go inside only if they’re part of the quote, etc.). Use block quotes instead for more substantial quotations. Use the correct (“curly”) symbols, not a double prime. Single quotation marks are not used in A List Apart except to demarcate quotations within quotations.

Numbers, percentages, and special circumstances

Dialogue: In general, use a comma to introduce dialogue and capitalize the first word. Interior dialogue: Use a comma and only capitalize if the dialogue itself contains a comma.

Foreign words: Use <em> to italicize, unless the word is well known to readers or it appears in the dictionary.

Numbers: Spell out numbers zero through nine and use numerals for 10 and up.

Percentages: Use “percent” in text (“95 percent of the time”), but use “%” in more technical contexts (“the survey shows that 25% of people reported X, 14% reported Y”).

Pronouns: Use “they” as a singular, gender-neutral pronoun.

Words used as words: Set in quotation marks.