Creating a writing style guide

illustrations illustrations illustrations illustrations illustrations illustrations illustrations

Published on 25 August 2022 by Andrew Owen (6 minutes)

When I switched from journalism to technical writing, the two things I missed the most were style guides and editors. When tech writing departments are downsized, editors are the first to be let go. On three occasions when I was the lone writer in an organization, I created my own style guide from scratch. But even when there is a style guide, it may not be current with modern terminology or language use. If you have to write customer-facing content as part of your job, especially if you didn’t train as a writer, you need a style guide.

When I started out in technical writing, unless you worked for Apple or Sun, the “Microsoft Manual of Style for Technical Publications” (3rd edition) was the most commonly used style guide. And it was a decade out of date with nothing useful to say about the internet. I think the screen captures were from Windows 95. It didn’t get updated until 2012. The other style reference was the “Chicago Manual of Style”, which was aimed at academia and also had nothing useful to say about the internet until its 16th edition (published in 2010).

The third reference book was a dictionary. Unless you worked for Apple or Sun, or a British company, it was “Merriam-Webster’s Collegiate Dictionary”. Unbeknownst to most British people, there are two distinct spelling conventions for British English: Oxford (that prefers the original -ize endings for words of Greek or Roman origin), and Cambridge (that prefers the later -ise endings introduced by the French). Aside from Canada (that mixes and matches American and Cambridge), the former colonies have settled on -ise endings.

If you don’t already have a style guide, you should create one. But you don’t need to start from a blank sheet. It should be a short document that lists the main style sources for technical terms, general writing and spelling, any deviations you want to make from those guidelines and a list of any domain-specific terminology. My recommended style sources are all available online:

I’ve used the “Chicago Manual of Style”, but I find its academic style more suited to publications with a long lead time, such as you might find in a waterfall development environment. For technical writing in an agile development environment, I find Associated Press’s newspaper style is a better fit.

When writing for an international audience, I use International English (American English). There are many regional variants, but the most popular alternative to International English with a consistent formalized spelling is Hiberno English (-ise endings). If you’re writing exclusively for an Australian, British, Irish or New Zealander audience, you can use the Cambridge English Dictionary”. Other regions will typically accept documentation in International English.

If I could go back in time and prevent the publication of one book, Strunk & White’s “The Elements of Style” would be a strong contender. I disagree with Geoffrey K. Pullum that it is mostly harmless because its disciples think that they understand how to write well, when often they don’t.

Common errors

Developers are not trained writers. Most of them would rather write code than English. If you’re a developer and you write, or if you have to edit developer docs, these are things to look out for:

  • after (not once)
  • and so on (not etc.)
  • article (not post)
  • because (not as or since)
  • can (not are able to/have the option to)
  • center (spelling)
  • click (not click on)
  • dialogue (not dialog except as a UI element in developer docs)
  • done (not finished)
  • enable (not allow except when referring to access control)
  • enter (not input)
  • exclamation marks ( ! banned except in birthday greetings where one is permitted)
  • for example (not e.g.)
  • for more information (starts a sentence: see for a cross-reference, refer to for an external link)
  • fulfillment (spelling)
  • help (not facilitate: avoid latinates)
  • IDs (capitalization)
  • is/are (not will be: passive voice)
  • list (not dropdown)
  • organization (spelling)
  • please (banned)
  • proper (banned except to describe nouns – most overused word in English)
  • set up (action)
  • the following (banned – always redundant)
  • that is (not i.e.)
  • that/which (contracting/expanding clauses)
  • to (not in order to)
  • URL (capitalization)
  • use (not usage)
  • use (not utilize: avoid latinates)
  • user’s (apostrophe)
  • using (not via)
  • want (not wish/would like)
  • you should (not it is recommended to)

My reasoning is:

  • Readers may not have English as a first language:
    • Avoid temporal ambiguity.
    • Don’t use Latin abbreviations (not all languages have Latin origins).
    • Don’t use latinates (utilize, facilitate and so on)
    • Don’t use words to mean more than one thing (once should only mean one time).
  • Use American English exclusively. I’ve seen mixed British and American English in variable names in code, with predictable results.
  • Use the active voice where possible, but not when the passive voice sounds more natural when you read it out loud.
  • When it comes to capitalization, developers instinctively write in CamelCase.
  • Readers consider any task that starts with please as optional.
  • Avoid words that machine translation frequently mistranslates.

Style preferences

There are some areas that Microsoft’s online style guide doesn’t cover. There are also some cases where I deviate from Microsoft’s advice.


A common error is putting the action before the reason. Write “to achieve X, do Y”, not “do Y to achieve X”.


I prefer to stick to these four admonitions:

  • Warning: Risk of injury, security breach or data loss.
  • Caution: Something that may prevent an intended action from being completed.
  • Note: Something sufficiently important in the text that it deserves to have attention drawn to it.
  • Tip: Advice that the reader can safely ignore.

They should only contain text. They shouldn’t appear in tables. And don’t put two or more next to each other.


Microsoft recommends the use of contractions (don’t, it’s, and so on) except when emphasizing a negative (do not). They help to create a more informal style of communication, which is why I use them in this blog. But I’d avoid them in any corporate communications because of the potential for misuse. But if you do use them, “it’s not” has one fewer syllable than “it isn’t”.


In online text, provide thumbs up and thumbs down feedback buttons linked to your analytics provider.


Use sparingly. Crop as tightly as possible.


Avoid fantastical terms in technical documentation (appears, wish, wizard and so on).

Navigation of the UI should have its own introductory topic. You can reference it but don’t repeat it. Don’t use right angle brackets (UI items often get moved around).

UI items

Use the UI item name exactly as it appears. If the name is missing or problematic, insist that engineering changes it.


Underline is a hangover from typewriters. Don’t use it.

Writing for a diverse global audience

I have a whole separate article on this topic.