Writing Style Guide

In the nascent days of HTML5 Doctor, I wrote Rich an e-mail asking if he wanted someone to copyedit the blog. He kindly excused my presumptuousness and set up a WordPress account for me, despite a complete dearth of any credentials on my part. This guide codifies some of the conventions I’ve adopted and invented over the past two years.

My goal in editing your articles is only clarity and correctness. I don’t want to take away your voice and make everyone’s writing sound as uniformly bland as my own. The less I have to change during editing, the more your writing remains your own. This guide will also become more necessary as we introduce more guest authors, even if only for the section on markup.

This isn’t a general guide to good writing. It’s specific to this blog, although I did include some broad suggestions to fix the commonest mistakes I see. I threw in some links at the end if this leaves you randy for more writing tips.

So try to stick to these guidelines, make your writing informative and interesting, but most importantly, have fun! Or whatever.

Grammatical Style

This section addresses a lot of subjective stylistic issues. Many points could probably be debated, but the point is to keep the writing consistent within and across articles.

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>
Use sentence case with punctuation for complete-sentence headings.

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>
Use title case for incomplete-sentence headings.

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>
You unambiguously ate your macaroni and cheese separately from your salmon chips.

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.
You’re not writing at a low-brow gadget blog. Don’t link like this.

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>.
Mmmmm, blinky…

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.

Markup

Being, you know, a blog dedicated to HTML5, our markup should be as tight as a…okay, it should be damned tight. Your knowledge definitely trumps mine here, so if there’s anything in this section that’s questionable, please do correct it and let me know.

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>
Permalinking an article 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>
Works in my browser. Ship it!

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>
Asides make sense so long as you don’t look at the code.

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>
A typical code sample structure

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.