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:
- “Microsoft Writing Style Guide” for technical terms.
- “Associated Press Stylebook” for general writing guidelines.
- “Merriam-Webster” for spelling.
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.)
- 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)
- that is (not i.e.)
- that/which (contracting/expanding clauses)
- to (not in order to)
- URL (capitalization)
- use (not usage)
- use (not utilize: avoid latintes)
- user’s (apostrophe)
- using (not via)
- want (not wish/would like)
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.
One area where I differ with modern technical style is in the use of contractions (don’t, it’s, and so on). 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”.
Writing for a diverse global audience
I have a whole separate article on this topic.