Book Review
This is my review (and notes) of the book Docs for Developers: An Engineer’s Field Guide to Technical Writing by Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse. I purchased this book because I am passionate about good developer docs. I can easily spot good developer docs while working on a project but find it hard to write them myself in a way that is useful to myself and others. This is a skill that I want to get better at so I thought that this book would help.
Chapter 1 Notes
This chapter is all about understanding your audience. This chapter seems geared more towards client-focused documentation, where you have a product (like an API) that you want clients to read. While this information is useful, and complete, it seems to be outside the scope of what docs I typically write, which is supplemental developer docs for internal teams to use to understand some service that my team maintains. I’ll definitely keep the points raised in this chapter in mind for when I have a need for more client-focused documentation.
I like the idea of a friction log. The authors define it as:
A friction log is a journal in which you try your software as a user would and record your experiences. To record your experience, log each step sequentially, noting the behavior you expect and the actual behavior of your software.
I’ve never done anything explicity like this, however I can relate to the process. To put it into my own experiences, my team typically writes docs for the rest of the team to consume, as I mentioned before. We have an agreement on the team, that if any dev reads docs and they don’t quite make sense to the dev reading them it is their responsibility to update the docs to make more sense. This to me has some relevance to a friction log because you have a real-world scenario where your intended audience is reading/working through your documentation and they just happen to also have the ability to improve it directly.
Overall Review
After chapter 1 I found 90% of the book pretty standard information and got nothing out of the information that I really thought was worthwhile. For this reason I stopped taking individual chapter notes. There was one section in one of the final chapters that explained some of the most common ways to organize your docs site. It gave me some ideas of how to organize the docs that I write for work in a way that makes the information grouped in a way that’s easy to find stuff.
I give this book 2 stars.