Writing Styleguide

Language, Voice, and Persona

Write with the intent of coming across as a manual describing a tool. The tool is not a friend or a person, but a machine. The machine has one job, and the machine wants to do the job well, and efficiently. With efficiency in mind, the language will be sparse and sparing, but with intense clarity.

With that in mind, the writing should come across in a few ways:

• Laconic, write clearly and with few words
• Formal, but not intimidating or pretentious
• Trustworthy and honest
• Straightforward and plain

With this persona in mind, correct grammar and language is forefront, with no humor nor colloquialisms. Write as if words were expensive, and the budget were very tight.

Grammar

Correct grammar, obviously. Full stops, commas to ease juxtapositions, lift and separate phrases, and separate listed phrases or words. Use the Oxford comma.

Unless part of a phrase or word group, punctuation always falls outside of a hyperlink. For example:

<a href="some-link.html">This</a>, <a href="some-link.html">That</a>, and others.

The last words in any given paragraph or other block-level elements are separated by a non-breaking space to prevent widows.

A period is followed by a single space. Smart quotes (“ and ”) should be used instead of straight quotes. Regular dashes are used for compound words (e.g. one-time fee, comma-separated list), en dashes (–) are used for ranges (e.g. 1–10, January–December), and em dashes (—) are used to cite authors and origins of quotes, preceding closing remarks, and for abrupt breaks in text (similar to, but more aggressive than parentheses.)

Example:

When grammar-checking, always remember one rule—do it often and do it well. However—and I say this with caution—this rule may be broken 3–5 times a year, in recognition of national holidays.

In quotes, terminal punctuation exists outside the closing quote mark—unless the terminal punctuation is part of the quote itself. For example:

He said it was “in our best interest”. I knew it to be true (though I wish it weren’t.)

Semicolons are used to separate juxtaposing sentences or phrases, or to separate list items which themselves contain comma-separated words or phrases. Colons are always used to introduce examples and lists. Blockquotes are used to frame non-original and secondary quotes that run longer than a single line.

Paragraphs—regardless of content—must not exceed more than around 10 sentences. Content must flow so that it is neither one long block of text, nor hundreds of separated single-sentence paragraphs.

Horizontal rules should be used to separate content into sections, or draw a rule before adding editorial notes and footnotes.

Try not to use us, our, we, you, my, mine, I, their, they.

Do not use he, his, her, hers, she.

Use the imperative sentence form over the implicit.

Examples

Wrong

Create a branch for your feature work, use the issue number from the ticket you created in step 1 as a prefix for the branch name.

Correct

Create a branch for the feature work, use the issue number from the ticket created in step 1 as a prefix for the branch name.