No. 210

Style Guide

The A List Apart style guide is available in two formats: PDF (download) and HTML (below).

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.

A List Apart House Style

Page Titles

With few exceptions, page titles are handled as follows:
Subject of page (in sentence case): Name of Magazine (initial caps)

Examples:
Web design content and tutorials: A List Apart
XML feeds: A List Apart

When it improves readability, we can alter the format slightly.

Examples:
About A List Apart
Credits: Who makes A List Apart?

Consistency is important, so you’ll need a really good reason to be an exception.

Article Titles, Headlines & Subheads

Title-case article titles. Sentence-case article headings. Neither take terminal punctuation unless a question mark is required. Neither take the serial comma and both use the ampersand in place of “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.

Examples:
Big, Stark & Chunky (document title and article title)
A different way to view the web (article header or subhead)

Lists

Code Examples

Mark up inline code examples with the code tag; use neither accompanying angle brackets nor quotation marks. Mark up larger code examples with the pre tag; begin examples with flush left and add two spaces two per indent thereafter. If we need to, we’ll re-break code examples to fit the magazine’s layout.

The Interhighwebnet

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

Linking

Choose link text that concisely indicates the nature of the linked document. Do not link terminal punctuation. Prefer shorter links to long ones. Link to well-established websites rather than to ephemeral ones when possible to decrease link rot.

Avoid blind links: if, for example, you link a few words in the middle of a sentence to a book page on Amazon.com, provide title text so that the reader doesn’t have to follow the link to find out what kind of clever comment you’re making.

Alt Text

Accompany each illustrative image with alt 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 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 & Treatment Fun

Geeking Out on Capitalization

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 phase, 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.

Formatting Articles for Publication

There are three acceptable formats for the delivery of the final draft of your article:

If you use XHTML, please limit yourself to clean, simple markup. The h1 tag is reserved for use as a page header, so please use h2 through h4 as needed in your article. Please also note the preferred HTML entity encoding list; it makes production far simpler if you correctly encode your punctuation and special characters.

If you use Microsoft Word, please use the Styles function to mark up your headers and subheads. Note link text in square brackets, with the URL in parentheses following your desired text.

Example:
[Jason Santa Maria]’s (http://www.jasonsantamaria.com) website sharpened my bicycle.

If you use plain text, please link text in square brackets, with the URL in parentheses following your desired text. Please note text styling in the same way. Alternately, you may use Textile’s text-styling marks.

Example:
[Jason Santa Maria]’s (http://www.jasonsantamaria.com) website [sharpened my bicycle] (bold/strong emphasis). (parenthetical method)

[Jason Santa Maria]’s (http://www.jasonsantamaria.com) website sharpened my bicycle. (Textile method)

Images & Example Files

Images can be either exactly 540px wide (full-column width) or 260px or less wide (partial-column width). We prefer the width-to-height ratio to be no more than 2:1. So a 540px-wide image shouldn’t be taller than 270px or so except when absolutely necessary.

PNG, GIF, and JPEG are all acceptable submission formats. GIF or PNG are preferred for images in which text is key. (You would not 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).

Example files should be marked up according to the guidelines above, and should include a page title formatted as follows: Article Title: Example #1: A List Apart.

Author Bios & Photos

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

Examples:
Dean Allen publishes the world–wide web sites Textism and Cardigan Industries, and is a frequent writer and lecturer on typography and editorial design. He lives in the South of France. (31 words)

Brian Alvey builds standards-friendly publishing systems for sites like A List Apart and companies like his own Weblogs, Inc. He is the creator of Blogstakes, an experimental site that rewards bloggers for linking to contests. (35 words)

Author photos don’t need to be professional portraits, but should look somewhat polished. A List Apart will prepare them for publication, so please send them as un-tweaked files of a reasonable resolution so that we can adjust them and shrink them for final placement. 400px by 300px is a nice minimum size.

Editorial Checklist

HTML Entities For Special Characters
& ampersand &
< less-than &#60;
> greater-than &#62;
¢ cent &#162;
£ pound &#163;
¥ yen &#165;
€ euro &#8364;
™ trademark &#8482;
© copyright &#169;
® registered trademark &#174;
« angle quotation mark (left) &#171;
» angle quotation mark (right) &#187;
¿ inverted question mark &#191;
– en dash &#8211;
— em dash &#8212;
‘ left single quotation mark &#8216;
’ right single quotation mark &#8217;
“ left double quotation mark &#8220;
” right double quotation mark &#8221;
… ellipsis &#8230;
‹ single left-pointing angle quotation &#8249;
› single right-pointing angle quotation &#8250;
À capital a, grave accent &#192;
Á capital a, acute accent &#193;
 capital a, circumflex accent &#194;
à capital a, tilde &#195;
Ä capital a, umlaut mark &#196;
Å capital a, ring &#197;
Ç capital c, cedilla &#199;
È capital e, grave accent &#200;
É capital e, acute accent &#201;
Ê capital e, circumflex accent &#202;
Ë capital e, umlaut mark &#203;
Ì capital i, grave accent &#204;
Í capital i, acute accent &#205;
Î capital i, circumflex accent &#206;
Ï capital i, umlaut mark &#207;
Ñ capital n, tilde &#209;
Ò capital o, grave accent &#210;
Ó capital o, acute accent &#211;
Ô capital o, circumflex accent &#212;
Õ capital o, tilde &#213;
Ö capital o, umlaut mark &#214;
Ø capital o, slash &#216;
Ù capital u, grave accent &#217;
Ú capital u, acute accent &#218;
Û capital u, circumflex accent &#219;
Ü capital u, umlaut mark &#220;
ß small sharp s, German &#223;
à small a, grave accent &#224;
á small a, acute accent &#225;
â small a, circumflex accent &#226;
ã small a, tilde &#227;
ä small a, umlaut mark &#228;
å small a, ring &#229;
ç small c, cedilla &#231;
è small e, grave accent &#232;
é small e, acute accent &#233;
ê small e, circumflex accent &#234;
ë small e, umlaut mark &#235;
ì small i, grave accent &#236;
í small i, acute accent &#237;
î small i, circumflex accent &#238;
ï small i, umlaut mark &#239;
ñ small n, tilde &#241;
ò small o, grave accent &#242;
ó small o, acute accent &#243;
ô small o, circumflex accent &#244;
õ small o, tilde &#245;
ö small o, umlaut mark &#246;
ø small o, slash &#248;
ù small u, grave accent &#249;
ú small u, acute accent &#250;
û small u, circumflex accent &#251;
ü small u, umlaut mark &#252;
ÿ small y, umlaut mark &#255;
Хостинг от uCoz