Review of Technical Writing for Software Developers

Just around the time I was complaining about the scarcity of books on technical writing, I got a copy of Technical Writing for Software Developers by Chris Chinchilla, a regular of the Write the Docs community. Delighted by the chance of reading a book from one of the sharpest pens in technical writing, I set aside some time to read through the nine chapters and write a review. The book taught me little I didn’t already know – Chris and I use the same tools and methods. The biggest value I extracted from TWfSD is its reflection of the times: it spurred lots of thoughts on the future of our profession and how we promote it.

Who knew? You can write about tech writing without being a bore

Those who have interacted with Chris know about his wit and intelligence. The 167 pages of TWfSD brim with irony and British sense of humor, a feature that makes this one of the most entertaining and digestible books on the topic. It’s no small feat for a field traditionally associated with dry seriousness. Throughout the book, Chris carefully tells personal stories and presents his own opinions in a way that enriches the points he’s making. In this sense, I read TWfSD not as a handbook, but as a transcript from a week of onboarding sessions at a new job, Chris patiently explaining the gist of the job to a new writer.

While reading TWfSD I found myself nodding a lot. Chris presents the profession as it’s practiced today in small-to-mid software companies. All the practices and tools introduced by the book are relevant and modern, and Chris is very honest in selling both the tools and the craft of technical writing, having no qualms in presenting shortcomings and obstacles when necessary. While he acknowledges that “tech writing is everywhere”, Chris doesn’t shy away from recognizing the difficult moment the industry is going through. The positive note? That “we may write less for direct human consumption, but we will still be writing.”

I admired the part where Chris makes a negative presentation of technical writing by stating what tech writing isn’t, because trying to define the shape of tech writing is as risky as pacing over quicksand. While his assertion that technical writing isn’t interface copy is formally correct, I think it’s false in practice, as I believe that the act of communicating technically doesn’t end with user manuals. On the other hand, I wholeheartedly agreed at separating technical writing from blogging or marketing, an association that has been running rampant on social media in recent years and hasn’t helped the field a bit.

Developers, developers, developers!

The soul of the book consists in persuading software developers that spending time and effort in writing docs and becoming part-time (or full-time) documentarians is worthwhile. Although the developers I know are more adept at reading about best practices in blogs or forums, TWfSD is short and compelling enough that it might succeed at the task of converting developers to the tech writing’s cause, however improbable that might seem to some. A book like this is a great instrument for getting the documentarian’s foot into the door of an engineering team. As Chris brilliantly puts it, “Documentation makes engineering look good.”

The focus on developers as the audience makes reading TWfSD a different experience for technical writers, who might find it too focused on practical aspects and tooling and less concerned with conceptual models or theories of documentation. Chris’s book touches on all the relevant topics, but if there’s an underlying philosophy or conceptual model of documentation, I couldn’t find it. It was not always clear to me who Chris was addressing at times (for example, when introducing HTML5 to developers, which in the case of frontend developers is a bit like presenting grammar to English literature majors).

I think the lack of conceptual bits is coherent with the author’s view of docs as an aspect of product development, a noble and necessary endeavor, but not one necessarily complex or rich enough to warrant a detour through the lands of Diataxis (sigh) or similar cargo cult constructs. What I found slightly more worrying is the lack of focus on the process of tech writing, which might give away the impression that tech writing can be refactored and replaced by some clever AI integration further down the road. Gone are the project management side, the chasing of SMEs, or the Jedi mind tricks we use all day. Oh well.

Will books like this help technical writing grow as a profession?

Chris’s book compares favorably to the excellent Docs for Developers, mostly thanks to the lighter, more ironic tone of the former, something hard to achieve when a book is written by a collective. The content, length, and structure are quite similar, though there’s an appendix in Docs for Developers that I sorely missed in TWfSD, that is, “When to hire an expert”.

Instead of closing with a note on technical writing as a career, or on the need of hiring technical writers, TWfSD opportunistically ends with a chapter on AI; this makes lots of sense given the Zeitgeist we’re traversing, but otherwise feels like an abrupt ending to me. It’s almost as if Chris forgot or declined to acknowledge that dedicated technical writers are a necessity when scaling up documentation efforts. It made me wonder if Chris would rather only have developers writing documentation for developers, which seems the prevalent position among startups. I’m pretty sure this will be amended in a second edition.

With few books on technical writing, and even fewer trying to push tech writing into the minds of other professionals, TWfSD is an excellent, necessary book that capably bridges the gap between engineering and tech comms by directly addressing our partners in crime, software developers. I think both Chris and I would agree on making technical documentation a mandatory subject for Computer Science degrees, alongside modern DevOps and PMO techniques. This book could be the basis of a “Documentation 101” course in the syllabus of any modern CS degree (and I’d certainly pay to see Chris as the instructor).

My last thought as I was placing TWfSD on the tech comms shelf of my library was “Does writing books on technical writing help technical writing grow as a profession?”. While books provide the field with a certain visibility in venues like Amazon, I can’t help but think of them as a short-lived attempt at reaching folks who are consuming content in completely different ways, be they social media, blog posts, webinars, or free guides. Tech writers often buy books to reassure themselves about their career choice. Newcomers? I think they would be better served by free content. We should be blogging more at the same time we’re publishing more books.