Essential works on technical communication
Last updated: Jun 22, 2023
These works have most influenced my approach to technical communication.
It turns out that none happen to be about technical writing in particular. For resources about technical writing and documentation, head to the beloved WriteTheDocs site and community, or read about the beloved Diataxis framework.
- Style: Lessons in Clarity and Grace. By Joseph Williams and Joseph Bizup.
- Trees, Maps, and Theorems. By Jean-Luc Doumount.
- Non-Designer’s Design Book. By Robin Williams.
- The Visual Display of Quantitative Information. Edward Tufte.
About writing software documentation
- Developing Quality Technical Information: A Handbook for Writers and Editors. By the IBM content team.
Information Architecture for the Web and Beyond.
About the variety of subjects that fall into the discipline of information architecture.
Great examples of technical writing
The Awk Programming Language. By A, W, and K.
Fantastic. The first chapter starts with an overview of useful one liners, the next describes the entire capabilities of the application, and the subsequent chapters provide detailed guides for increasingly esoteric applications of Awk, starting with formatting data for reports and finishing with making assemblers and interpreters.
Blog and zines. By Julia Evans.
Julia Evans’ work—especially the zines—is a fantastic example of inclusive, respectful technical communication. All of these topics are complex, but, since she writes in such a clear, fun, and joyful way, the effect is inviting. As a non-expert, I feel encouraged to try and understand things that I previously believed were prohibitively difficult.
Practical Typography. By Matthew Butterick.
This book made me excited to learn about typography.
Finishing a tube of chapstick. Reddit comment.
The eye for detail, the precise vocabulary, and the rhythm and structure of the sentences make this comment not only informative but even beautiful.
What about docs?
I hesitate to cite specific documentation pages, because they can be as ephemeral as applications. What’s more, if I’m not using the docs, I can’t comment on how well they serve their readers. In the times when I have needed to develop something, I’ve especially liked the docs for the Mozilla Developer Network, Postgres, OpenAPI, Digital Ocean, RevealJS, Emacs, and k6 (I’m biased towards the last one).