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 to see the contents of my lists, scroll down to the first heading below. I have listed all of my references in a technical-writing Zotero library, except for my list of technical style guides.

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. This includes buzzwords and jargon that your audience won't understand. 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 some times bends to style but, ultimately, breaks away from rules. I prefer an easily–understood language that caters to one’s audience without using difficult words and long adjectives to theatrical documentation.

Your audience will not like 'clever'. They like clarity.

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 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 to teach their audience to, 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 your audience and write as though they are looking over your shoulder. Your writing language may not be their mother tongue, which means you should use simple words and short sentences to make your documentation as readable as possible. You probably recognise the feeling of attending a presentation where the presenter uses strange abbreviations or talks about things that have nothing to do with the intended subject; this kind of senseless talk turns people off, which also goes for readers: they stop reading and go elsewhere. Senseless language is, academically speaking, called bullshit for good reason: read about how bullshit ruins rational thought¹. By the way, there is far more research available on how to detect and avoid creating bullshit.²

Engage with your readers as often as possible. 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 but almost never replace the many types of feedback that human beings provide. Silence from readers of technical writing is the opposite of golden.

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 and then analyse what can and needs to be improved. Constantly make notes on how people react to your documentation. Reach out to internal and external readers and engagingly ask them what they think of your documentation; remember, bad documentation is rarely reported, and 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 let players press a button to have rails erect on both sides of a lane to prevent a ball from landing in the gutter⁴? Writers do the same. We use other names for our rails: grammar, style guides, stylebooks, standards, rules.

Standards are sets of rules. 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 once 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. Personally 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 the internet. Make either of these assumptions and you will fail. Instead, consider how many of our favourite authors have used (and still use) pen and paper to write your favourite books (a lot of them likely did). Writing by hand, as opposed to by keyboard, provides forethought. Consider other benefits from writing by hand. When in doubt (and if possible), leave your computer and jot things down by hand: it can help. Other times, do something else for a while or have a sleep. Rest can be your best tool to resolve any writing problem.

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. 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. This style guide is often 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 that is no longer the case. The printed copy is still in print. 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 the 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. I still have a lot of love for the Associated Press stylebook.

• 2010. Oxford Dictionary of English. Oxford University Press, USA.

  I 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. Kill it with fire!

• 2003. Merriam-Webster’s Collegiate Dictionary. Springfield, Mass: Merriam-Webster.

  Merriam-Webster's is my preferred standard dictionary for American English (even though others, for example, American Heritage Dictionary, are perfectly fine and, at times, even better, depending on your use cases).

• Moran, Joe. 2018. First You Write a Sentence. Penguin UK.

  Moran's book shows why we should 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–tuning.

• Klinkenborg, Verlyn. 2013. Several Short Sentences About Writing. Vintage.

  Klinkenborg's book oozes of style, which something that he masters. This book clasped my attention and it was hard to stop reading. 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 writing and design.

• 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 the internet is something from which nobody can hide.

  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 manually piece them together to figure something out. This book shows us why and how we should consider to write in tidbit form, and how to assemble our small pieces into articles.

• 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 and Readwise allow us to annotate web pages and books and collect our annotations in a neat way. When writing technical documentation, annotation does matter. Personally, I use Hypothesis for everything from tagging resources and viewing them on one web page to conducting documentation reviews. I use Readwise to annotate books and web pages and sync my contents to Obsidian.

• 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 created the standard, but by people in many different industries. 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, for example, 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 latest book of the bunch. It’s mainly for developers. It’s fairly modern and contains a few very good tips for modern technical writers, especially those who adhere to writing 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/.

  This is, without a doubt, the best free online course on how to document APIs. It is available in different formats. I warmly recommend a subscription to Tom’s newsletter.

• 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 going 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 plot description:

  ‘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 who was at times of very 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 those style guides and you will find out that very few systems are perfect. This book shows how one person can influence a universe of people.

• 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 am not. Instead, I write, rewrite, have others comment and chip in, and edit again. This book is a nice dive into how the review process works.

Technical style guides

The Microsoft Style Guide is not the one–and–only style guide. Here are some other ones that I use:

• Google developer documentation style guide
• Apple Style Guide
• Write the Docs, Accessibility guidelines
• Write the Docs, Reducing bias in your writing
• IBM developerWorks Editorial style guide
• Red Hat Technical Writing Style Guide
• Splunk Style Guide
• DigitalOcean Documentation Style Guide
• Salesforce Style Guide for Documentation and User Interface Text
• Rackspace Writing guidelines
• OpenStack Writing style
• MongoDB Documentation Style Guide
• Conscious Style Guide
• 18F Content Guide
• A11Y Style Guide
• Mailchimp Content Style Guide

Language, grammar, and help

I will not go into any detail about these books, but if I had a gun to my head and my would–be assassin asked me to name five of these to hand to a fresh technical writer, I would stutter the book titles from Dreyer, McColloch, Graves, Adger, and Ginna.

• 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.
• Ginna, Peter. 2017. What Editors Do: The Art, Craft, and Business of Book Editing. The University of Chicago Press.
• Wayne C. Booth et al. 2024. The Craft of Research, Fifth edition. The University of Chicago Press.

Software and web sites

According to some, there is 71% risk that I will be replaced by a robot ³; honestly, I have little faith that will actually happen during my lifetime, mainly as developers are human. Enough said.

• Obsidian

  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.

• British National Corpus

• Corpus of Contemporary American English

• Google Books Ngram Viewer

  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.