Voice and Person #

To the extent that your mortal soul can bear, avoid using the passive voice. The subject of your sentence should be performing the action of your sentence:

The page is rendered by the browser. <!-- barf -->

The browser renders the page. <!-- yum! -->

Such sentences are more interesting, brief, direct, clear, and better. (Yes, more better.)

Address your writing to a specific audience. It’s fine to talk about any of “you” or “we” or “I”, but keep the person consistent throughout the article.

Headings and Subheadings #

If your heading is a complete sentence, write it in sentence case and end it with proper punctuation:

<h2>What ever happened to Compuserve?</h2>
<h2>It’s the economy, stupid!</h2>

If your heading is a sentence fragment, write it in title case and leave off the end-sentence punctuation:

<h2>Headings and Subheadings</h2>
<h2>Applying Kittens to Your CSS</h2>

The Serial Comma #

I write using the Oxford (serial) comma, and nobody will ever convince me to do otherwise. Nobody. Ever.

<p>I ate gumbo, macaroni and cheese, and salmon chips.</p>

Numbers #

Spell out numbers less than one hundred. Beyond that, use your best discretion. Place a hyphen between the tens and the ones digits. Use a comma as the thousands-separator.

• one
• fourteen
• seventy-seven
• one thousand
• 18,397

Punctuation and Abbreviation #

• Feel free to write “it’s” instead of “it is”, or “I’m” instead of “I am”. Contractions make your writing sound more genuine and conversational.
• It’s okay to use an ampersand in a heading, a figure caption, or as part of a name (e.g., “Proctor & Gamble”), but don’t use them in prose.
• I’ve begun replacing straight quotes with curly quotes, but you don’t need to worry about typing them. I just find and replace.
• Considering our audience, I’d say it’s safe to leave off the <abbr> tag around these abbreviations: API, CSS, HTML, HTTP, IE, W3C, WHATWG, XML.
• Don’t abbreviate “JavaScript”, and do capitalize the “S”.

Hyperlinking #

Don’t link short phrases like “this” and “said” and “here” and “article”:

Refer to our prior <a href="...">article</a> on the <blink> element.

People should be able to tell what you’re linking to without any context other than the link itself:

Refer to <a href="...">our prior article on the <blink> element</a>.

One more minor point: if you hyperlink an entire sentence, the end-sentence punctuation is a part of the link. Otherwise, it’s not.

Britishisms #

As much as I’m aware of it, I leave intact any idiomatic British that you gents write, viz.:

• spelling differences like “ise” rather than “ize”,
• grammar differences like “as” rather than “since”,
• end-sentence punctuation placed outside of double-quotation marks, and
• other platitudes that I don’t recognize as ’Merkin English.

Let me know if I ever change anything that just gets your bangers in a mash.

Miscellanea #

Everyone loves a list, so I made two! The first contains a few common spelling and grammar mistakes I see here:

• “It’s” is a contraction of “it is”. “Its” is equivalent to “belonging to it”.
• “You’re” is a contraction of “you are”. “Your” is equivalent to “belonging to you”.

and the second is simply an assortment of other writing tips:

• I already said it, but let me reiterate: you will instantly improve your writing by rephrasing passive voice sentences in the active voice.
• Almost nobody knows how to use a semicolon correctly; myself included. Just forget it exists.
• Minimize ambivalence. You don’t need to preface all your thoughts with “I think” and all your opinions with “In my opinion”. Readers know this isn’t the Britannica.
• Brevity is the soul of wit.

Sectioning #

The prevailing convention here dictates one section per heading level and cascading heading levels (i.e., not starting over with <h1> for every section). Our layout already claims the top-level <h1>, so start with <h2> in your articles.

This convention allows us to link directly to individual sections within our articles. Attach an id attribute to your <section> and create a link within your section heading using that ID as a fragment identifier:

<section id="foo">
  <h2>Fooing Your Fooness to the Max <a href="#foo" class="permalink">#</a></h2>
  <!-- ... -->
</section>

If you’d like to number your headings — for example, in Ian’s article on multimedia troubleshooting — give your sections a class="numbered-heading" attribute. The headings in each such section will be numbered sequentially starting from 1.

Quoting and Citing, Especially the Spec #

You should definitely peek at Oli’s article on quoting and citing, since that part of the spec is in heavy flux right now. In the meantime, this seems to be how we cite blocks of text (yes, that’s an em dash):

<blockquote>
  <p>You should definitely peek at Oli’s article on quoting and citing, since that part of the spec is in heavy flux right now.</p>
  <footer>
    — <cite><a href="...">Brandan Lennox</a></cite>
  </footer>
</blockquote>

Asides #

Asides are so adorable!

<aside class="sidenote">
  <p>Trust me, readers respect authors who continually make up words.</p>
</aside>

<p>Because of our CSS, asides typically appear in the markup before the content they’re asiding.</p>

Code Samples #

Always wrap your code in a <pre><code>...</code></pre> structure, and pay attention to leading whitespace within the <pre>:

<pre><code><!-- Various -->
// Kinds
# Of Comments</code></pre>

Don’t add a line break between the initial <pre><code> and your first line of code. It screws up the spacing.

If you’d like to add a caption to your code sample (or if you just like the dotted blue lines like I do), wrap it in a <figure> element and add a <figcaption> like I’ve done throughout this guide. (Unlike headings, you should always write your figure captions in sentence case, but you only need end-sentence punctuation for complete sentences.)

I wrap HTML element names in a <code>&lt;...&gt;</code> structure. It’s pretty easy for me to do this in TextMate, so you don’t need to fret over it too much.