Creating a writing style guide
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.
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:
My reasoning is:
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:
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).
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.
I have a whole separate article on this topic.