I am a professional technical writer. When I started out, I desperately looked for tips and tricks. Internet was (and is) full of tips but I could not find a tech-writing bibliography.
This post is a list of tips, books, and other sorts of references that I use.
Before I start listing, there are a few things that I want to point out. If you only want my lists, they are listed under headings below.
Writing is often about style. Often, but not always. Style can be defined as a distinct manner of expression. Technical writing will always be styled, but preferably not by using theatrical expression, for example, buzzwords for the sake of seeming relevant. I see technical writing as a sibling to so-called academic writing (brief and correct) and a distant cousin to creative writing (can include wit and fun). I say this because even technical writing bends to style but, ultimately, breaks away from its rules. I prefer an easily-understood language that caters to one’s audience to difficult words and long adjectives.
Obviously, there is nothing wrong with adding a bit of personal flair to technical writing. This is proved by scores of funny, intelligent, and pedagogical writers. Wit goes a long way in capturing attention. Even emojis serve purpose. Some times, having read stale and bone-dry text for what seems like an eternity, you just want something else to happen; if your text is too stale, you risk the reader abandoning what you have so carefully crafted. On the other hand, technical writing is brief for good reason: readers often want to find what they are looking for and then leave. Most readers do not want to sift through aeons of ‘funny’ text, unclear headings, long sentences, inconsistencies, jargon, etc.
The best tip I can give about technical writing is this: technical writers are like aides to contractual murderers: they provide material so that a specific person can, as quickly as possible, finish their mission and leave. Brevity is appreciated by readers. To be succinct (in technical writing) is to truly care about the reader.
Know and constantly write for your audience. The language you write in is possibly not their mother tongue, which means you should use simple language and short sentences. Everybody has attended a meeting where the presenter uses abbreviations that only a few per cent know, or talks about things that have nothing to do with your life; this kind of senseless writing turns people off: they stop reading and go elsewhere. Senseless language is, academically speaking, called bullshit for good reason: read about how bullshit ruins rational thought1. There's far more research available on how to detect and avoid creating bullshit, by the way.2
Always speak and engage with your readers. Do not only rely on your colleagues to know how what your readers think (unless your colleagues are your only readers). Do not for a moment rely on surveys; they can serve perfectly well at times, but rarely provide the intellectual feedback that helps you understand what human beings think of your writing. Silence from readers of technical writing is not golden but the opposite.
Test your technical documentation. Have new readers try it out. Record their first-time reactions on video and do not steer them in any way apart from providing them with brief instructions if they get lost. Collect the results after you have tested your documentation with circa five people and then analyse what needs to be improved. Constantly make notes on how people react to your documentation. Contact your developers and readers, because, do not for a second think that anybody will let you know when your documentation is wrong; they will be frustrated and just nag about it, but it is up to you to make sure that your documentation is fresh and clean, as Outkast would put it.
Rules. Remember how some bowling alleys allow customers to press a button to have rails erect on both sides of a lane to prevent a ball from not hitting pins? Writers do the same. We use other names for our rails: style guides, stylebooks, standards, rules. Many names, they basically do the same.
Standards are rules to follow. Some standards are legally binding, some are not. If I write of how a tennis ball works, the risk of breaking law can be slight. However, if I write a user guide on how to run a nuclear power plant, erroneous writing can break laws, ultimately, bankrupt companies, and cause nuclear disaster. Remember, a misplaced semicolon caused a riot.
Technology. Some tools can help you. Other tools—I see you, spelling and grammar in Microsoft Word—claim to use ‘artificial intelligence’ to write for you, often with disastrous results; PDF link. You don’t need to try and master the English language, but you should learn some basic rules and the most common pitfalls when writing. Prsonally speaking, one of my main enemies is false friends. That’s just an example.
Books about writing may seem dated because they focus on printed media. Books may seem dated because they are not on internet. Make these assumptions and fail. Instead, consider how many of our favourite authors have used (and still use) pen and paper to write your favourite books; electronic or printed, the difference is often tiny. Writing by hand, as opposed to by keyboard, provides forethought. Consider other benefits from writing by hand. When in doubt, leave your computer and jot things down by pen: it can help. Other times, do something else and return to what was initially troubling you.
I’ve listed the first section in order of importance with the most important at the top, trickling down.
Technical-writing guides and rules
Alred, Gerald J., Charles T. Brusaw, and Walter E. Oliu. 2015. The Handbook of Technical Writing. Macmillan Higher Education.
I cannot say enough good things about The Handbook of Technical Writing. If you believe that its parts on written English that relate to handwriting are ancient, think again; there’s a reason why database design should be committed to paper before you learn it adequately (i.e. start using all-electronic equipment).
2012. Microsoft Writing Style Guide. https://docs.microsoft.com/en-us/style-guide/welcome/.
I use the Microsoft Manual of Style at work. It is nice to have, runs on GitHub (which means that documentation bugs can be submitted via GitHub), but lacks a forum through which its contents and roadmap could be discussed. At the worst of times, this style guide seems quaint, especially when you find Microsoft documentation that severely deviates from the guide. Still, it can be very helpful for a new technical writer.
Barr, Chris. 2010. The Yahoo! Style Guide. St. Martin’s Griffin.
The Yahoo! Style Guide used to be available online, but is sadly no longer. The printed copy is still in print, and even though it is a bit dated, I recommend buying a copy as it contains tips on style, grammar, formatting, writing for the web, and a million of little things, all tied up into one wondrous package.
University of Chicago. 2017. The Chicago Manual of Style.
I often see two main branches of professional writing styles: Associated Press Stylebook (AP) and The Chicago Manual of Style. To paraphrase Benjamin Dreyer, only godless savages do not live by the serial comma/Oxford comma; Chicago do, AP do not.
2010. Oxford Dictionary of English. Oxford University Press, USA.
I like and often use the Oxford English Dictionary as a mobile app. The paper version is very good. Please note that this is not the same as The University of Oxford Style Guide, which is only ever successfully used by pupils at that school.
2003. Merriam-Webster’s Collegiate Dictionary. Springfield, Mass: Merriam-Webster.
Merriam-Webster's is my preferred standard dictionary for American English (even though others, e.g. American Heritage Dictionary, are perfectly fine and, at times, even better, for different reasons and use cases).
Moran, Joe. 2018. First You Write a Sentence. Penguin UK.
Moran's book shows the reader to care about words. He treats the reader intelligently and the most attractive thing about this book is that it focuses on why we should care, not how; the later implicitly comes when one truly values words. The want comes first, then the fine-tune.
Klinkenborg, Verlyn. 2013. Several Short Sentences About Writing. Vintage.
Klinkenborg's book oozes of style, something that he masters. This book clasped my attention and it was hard to let go. Even the title says much about this book: short sentences are able to carry a reader for far longer than, well, long sentences would.
Zinsser, William. 2006. On Writing Well. New York: Harper Collins.
Truly great style live through the ages. This book is published in over thirty editions. It focuses on non-fiction writing. It's a great resource from a very careful and thoughtful writer.
Norman, Don. 2013. The Design of Everyday Things. Hachette UK.
Most user-experience designers who have read this book love it. I believe it can make technical writers open their eyes a bit more to how the visual world presents possibilities instead of problems; technical writers are often prone to shy away from visuals (images, videos, flowcharts) as they’re problematic for people with accessibility needs. Writing and designing go hand in hand, just as with technical writers and designers.
Baker, Mark. 2013. Every Page Is Page One. XML Press.
Mark Baker’s Every Page Is Page One is an instructive propaganda tool designed to show why rewriting content for internet is something that nobody can hide from.
Today, people search for answers in neat tidbits that help them to quickly understand and learn what they are looking for; people do not want to read aeons of different documents and be forced to piece them together to figure something out. This book shows us why and how to write in tidbit form.
Kalir, Remi H., and Antero Garcia. 2021. Annotation. MIT Press.
Annotation is a note added by way of comment or explanation. Modern tools like Hypothesis allow us to annotate web pages and books, while tying it all together. When writing technical documentation, annotation does matter. Personally, I use Hypothesis for everything from tagging resources and viewing them on one web page to documentation reviews.
n.d. Simplified Technical English (ASD-STE100). AeroSpace and Defense Industries Association of Europe.
Simplified Technical English (STE) is used everywhere, not only by the aerospace industry that made this standard. STE is, at its core, a list of words that should and shouldn’t be used—including replacement suggestions—when writing instructions in English. It’s also got some quite grounding and thought-through examples available for other stuff than mere words, e.g. suggested numbers of words per sentence.
Use this link to register for a free copy of the latest edition of ASD-STE100.
Halvorson, Kristina. 2012. Content Strategy for the Web. New Riders.
The best thing about this book is that it shows the value of establishing a content strategy to avoid the Hell where outdated, fragmented, unclear, and unknown documentation lives.
Bhatti, Jared, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse. 2021. Docs for Developers: An Engineer’s Field Guide to Technical Writing. Apress.
This is the newest book of the bunch, and it’s mainly for developers. Still, it’s fairly modern and contains a few very good tips for modern technical writers, especially those who adhere to docs-as-code.
Johnson, Tom. n.d. “Documenting APIs: A Guide For Technical Writers And Engineers.” I’d Rather Be Writing. Accessed August 5, 2022. https://idratherbewriting.com/learnapidoc/.
Harford, Tim. 2018. Messy: How To Be Creative and Resilient in a Tidy-Minded World. Abacus.
This book is actually not about writing, but about the importance of keeping an open mind. For technical writers, it best relates to our continuous need to know our audience in order to not fall victim of cognitive bias. The book contains many examples of times where people have benefited greatly from veering off the beaten path.
Winchester, Simon. 2010. The Surgeon of Crowthorne. London: Penguin UK.
This is an astonishing book that is not about technical writing. From the Wikipedia description of its plot:
‘The book tells the story of the making of the Oxford English Dictionary (OED) and one of its most prolific early contributors, William Chester Minor, a retired United States Army surgeon. Minor was, at the time, imprisoned in the Broadmoor Criminal Lunatic Asylum, near the village of Crowthorne, in Berkshire, England.’
In other words, this goes to show that one of the most important and influential dictionaries in the World was created by a fevered and intelligent person in poor mental health. As you engage with different style guides and, possibly, write your own (which is something I strongly recommend that you do), you will find inconsistencies in them and know that very few systems are perfect. This book is a perfect reminder of this fact, while it shows that one person can make a lot of difference.
Davies, Peter Ho. 2021. Art of Revision. Graywolf Press.
I wish I were the kind of writer who constructs neat sentences in their head. I’m not. Instead, I write, rewrite, have others comment and chip in, and edit again. This book is a nice dive into the review process.
Language and grammar
I won't go into any detail about these books, but if there were a gun to my head and my would-be assassin asked me to name four of these to hand to a fresh technical writer, I would say those by Dreyer, McColloch, Graves, and Adger.
- Adger, David. 2019. Language Unlimited. Oxford University Press, USA.
- Graves, Robert. 2017. The Reader over Your Shoulder: A Handbook for Writers of English Prose. Seven Stories Press.
- Dreyer, Benjamin. 2019. Dreyer’s English. Random House.
- Kirkman, John. 2006. Punctuation Matters. Routledge.
- Watson, Cecelia. 2019. Semicolon. Ecco.
- Kohl, John R. 2008. The Global English Style Guide. SAS Institute.
- McCulloch, Gretchen. 2019. Because Internet. Riverhead Books.
- Murphy, Lynne. 2018. The Prodigal Tongue. Oneworld Publications.
- Stamper, Kory. 2017. Word by Word. Vintage.
Software and web sites
According to some, there’s 71% risk that I will be replaced by a robot 3; honestly, I have little faith that will actually happen during my lifetime, mainly as developers are human. Enough said.
I could write for ages on the many benefits with Obsidian, but from a tech-writing angle, I say this: Obsidian used together with the plugin obsidian-vale, with all of its bundled styles enabled, and with Openly added (add custom linting styles to obsidian-vale), is absolutely blissful. It allows me to check text by using style guides from, for example, Microsoft and Google.
This is a lovely system that I’ve used as a reminder to write for different audiences more than to check for errors in style and grammar. It’s not perfect, which means that it’s not really up-to-speed with technical writing nor consistency. Errors and improvements that I have reported to the suppliers of Grammarly have, so far, not made their way into the product. Lastly, use this tool with caution: you might not want to use it to check code and text that is covered by intellectual-property rules.
- Corpus of Contemporary American English
These three corpora allow us to see how commonly a word or a phrase is used. Why would you want to do that? Well, you must know your audience in order to write for them. The corporas help us to choose phrases and words so that as many people as possible understand our documentation. By the way, as mentioned in my Language and grammar section, Lynne Murphy's The Prodigal Tongue is a highly informative book that shows how easy it is to mix up British and American English.
Ferreira, Caitlin, David Hannah, Ian McCarthy, Leyland Pitt, and Sarah Lord Ferguson. 2020. “This Place Is Full of It: Towards an Organizational Bullshit Perception Scale.” Psychol Rep, December, 16. 10.1177/0033294120978162. ↩
McCarthy, Ian P., David Hannah, Leyland F. Pitt, and Jane M. McCarthy. 2020. “Confronting Indifference toward Truth: Dealing with Workplace Bullshit.” Business Horizons 63 (3): 253–63. 10.1016/j.bushor.2020.01.001. - see also Herold, David M., Timo Dietrich, and Tim Breitbarth. 2020. “Banking on Bullshit: Indifferences towards Truth in Corporate Social Responsibility.” IJBM ahead-of-print (ahead-of-print). and Vladimíra Čavojová, Ivan Brezina, Marek Jurkovič. 2020. “Expanding the Bullshit Research out of Pseudo-Transcendental Domain.” Curr Psychol. 10.1108/ijbm-04-2020-0207. ↩
Since I started writing this post, the number has gone down from 89%. Fancy that. ↩