Style Guide

Contents

General notes

Articles written for publication on A List Apart use an informal, conversational tone, though not at the cost of clarity or correctness. Experts require neither excessive formality nor excessive casualness to express their authority. If you write with ALA’s readership in mind and sound like yourself, you’re most of the way there already.

Concise articles with snappy intros

Our article space is intentionally limited to a single page. There is no room for meandering, no space for encyclopedic completeness. You need to get in, score, and get out. State your idea clearly and quickly. If your tutorial solves a problem, state the problem. Don’t warm up to your subject by preceding it with generalizations. You don’t need to tell our readers that Tim Berners-Lee invented the web before getting to your point.

Keep your readers in mind

Experienced web professionals read ALA. If you dumb down your article, you will offend these readers. But our readers come from many backgrounds—a reader who knows all 317 CSS workarounds might not necessarily have heard of Edward Tufte—so take time to define your terms and provide pertinent background information, if only as a link.

On metaphors

Extended metaphors can provide gentle uplift and support, but they make poor lifeboats. Avoid extended cooking and spell-casting metaphors unless you can carry it off in a truly novel and delightful way. They may be apt, but are without question overworked.

Clarity first

Avoid unnecessary jargon, trendy constructions, vagueness, and buzzwords. Omit needless words. Make sure that pronouns point the way to their referents like the tidy signposts they are. Strive for brisk pacing and precise explanation. Limit the use of opaque idioms and pop culture references to non-essential points; no reader should need to be familiar with a particular song or movie to understand your central argument.

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.

House style

In general, we use U.S. English according to the Chicago Manual of Style, with Fowler’s Modern English Usage taking over in tricky situations.

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.”

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.

Article title or document title

Big, Stark & Chunky

Article header or subhead

Big, stark, and chunky

Elements

Inline elements should be presented in lowercase to maintain consistency with post-XHTML best practices and improve readability.

I then extract the content of the div and add it to the list.

Using Code

Any inline bits of code you use should be wrapped in code tags. Any stand-alone code blocks should additionally be wrapped in a pre tag.

Code blocks

Please use tab for line indentation. Each nested line is indented one tab from the parent.

Control structures such as parentheses require spacing on the outside only:

if (foo  bar) {
	// do something
}

An opening curly brace should be on the line of the command that uses it. The closing one should be on its own line (or if it is part of something like an else statement, on the line with the else:

if (foo  bar) {
	// do something
} else {
	// do something different
}

…or:

if (foo  bar) {
	// do something
} else if (foo rae) {
	// do something different
}

Functions

Function and method references in paragraphs should always have their associated () unless being addressed specifically as a function or method:

In this section we pass the variable to doSomething() and we’re off to the races.

…or:

In this section we pass the variable to the doSomething function and we’re off to the races.

Inline CSS

CSS properties should be wrapped in code. Inline property assignments should not include the semicolon.

Then we set color: #000 and go on about our business.

Or you can say:

Then we set color to #000 and go on about our business.

…if you prefer.

If you’re discussing width or height in general terms, don’t use code. If you’re referring to the width or height property, use code:

We then set the width to be 200px.

We then set the width property to be 200px.

CSS Blocks

In addition to following the above format guidelines, CSS blocks should be written with each property on a different line and with each selector on a different line.

p {
	color: #000;
	font-weight: bold;
}
em,
strong {
	font-size: 1.1em;
}

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.

Linking

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.

Punctuation

  • Acronyms and abbreviations: The acronym element is obsolete. Use abbr.
  • The ampersand: Avoid the use of 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.
  • Commas: Use the serial comma (the comma preceding the “and” before the last element in a list) except in article titles.
  • 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.
  • Em dashes: Do not leave a space on either side of the em dash. Use the en dash for enumerated date ranges.
  • Hyphens: Hyphenate compound noun phrases used as adjectives unless the noun phrase is so popularly used that hyphenation appears awkward. Do not hyphenate compound adjectival phrases whose first element is an adverb. And remember—as the man said, “If you take hyphens seriously, you will surely go mad.” (The man being, in this case as in so many others, the Oxford University Press style manual.)
  • Quotations: Position punctuation according to Chicago rules (periods go on the inside, etc.). Use block quotes instead for more substantial quotations. Use the correct (“curly”) symbols, not a double prime. Preferred encodings are available in Appendix A. As nice as they are, single quotation marks are not used in A List Apart except to demarcate quotations within quotations.

Capitalization details

The words “internet,” “net,” “web,” and “website” should be capitalized as seen here (which is to say, not capitalized) when they’re found in sentence-cased text. E-mail and e-commerce take the hyphen, but not a capital “e.”

When using title case, capitalize the first, last, and all other major words. Lowercase “and,” “but,” “for,” “or,” and “nor” unless they are emphasized in a particular heading.

Examples:

A New Hope for Embedded Fonts

Arguments For and Against FIR Strike Back

When a headline-style heading includes a hyphenated phrase, always capitalize the first element. Capitalize the second element unless it is an article, preposition, or any of the coordinating conjunctions noted above. Exception: if the first element is a prefix like pre-, post-, or anti-, or if the phrase is a written-out number, do not capitalize the second element.

When using sentence case, capitalize only the first word and proper names.