Modern technical writing - Andrew Etter 2016

Introduction

Given the pace of the software industry, I'll probably regret calling this book Modern Technical Writing, but Technical Writing in 2016 or What Currently Passes as Sane Technical Writing weren't any better. Books like this one have a short shelf life unless a subject matter expert meticulously maintains them, which I don't intend to do. Still, I imagine the book will hold its value for the next five years—probably long enough to make writing and reading it worthwhile.

I had the idea for this book a couple years after I started working as a technical writer. I had just finished interviewing some very nice, very experienced people from two massive Silicon Valley companies, and we just could not find common ground. Their impression of the job was that technical writers interviewed engineers, took copious notes, wrote drafts in Adobe FrameMaker, and waited several hours for some arcane process to build those drafts into printable books. These candidates mentioned page counts, XSLT, Perforce, and gerunds. They were proud that their page numbers were laid out recto-verso¹. None of them seemed to give any thought to their readers' actual needs, preferring their own criteria for what constituted a job well done. They used phrases like "clear, concise, correct, and complete" and avoided words like "searchable," "scannable," "attractive," and most egregiously, "useful."

These candidates weren't stupid; they were articulate and pleasant, well-educated and inquisitive. No, I believe they were products of a dysfunctional profession, a profession of misplaced priorities, judged for too long on meaningless criteria by managers who treat the Chicago Manual of Style like a holy text and would rather produce minimal value from a lot of work than tremendous value from far less work. Exceptional technical writers are force multipliers within the software industry. Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms. Technical writing matters, so I wrote this book to help people create documentation in a sensible way.

To be crystal clear, this book is about technical writing in the software industry. Most of the principles are universally applicable, though. If a particular recommendation doesn't seem relevant to your work, please take a mental step back and try to assess the high-level principles behind the recommendation. Maybe I'm completely off base, or maybe some kernel of wisdom is buried in my insufferable prose. In other words, please don't dismiss a good idea because of bad execution.

And thanks for reading.

— Andrew Etter

1. Recto-verso just means using slightly different layouts for the "right" and "left" pages of a book.↩