Andrew Etter - Modern Technical Writing: An Introduction to Software Documentation

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 yearsprobably 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.

Like all writers, technical writers aim to produce content that their intended audiences will read and find useful. This has to be the goal, because any other goal is absurd. Keeping it in your head at all times will help you produce more valuable work in any profession. Consider a few common misconceptions about technical writers:

• Technical writers produce formal documentation.

  In this case, "formal" means unnecessarily stuffy and repetitive, the sort of writing that causes people to skim rather than read. When your ideal readers are tee shirt-clad software developers who mainline Hiball Energy and spend most of the year looking forward to Burning Man, it's safe to assume a more casual writing style.

  Note

  This does not give you license to write in an unprofessional or sloppy manner. Writing should not call attention to itself by being too formal or too casual. Occasionally reminding readers that human beings produced their documentation is fine. Making readers think that they are reading rough drafts is not.

• Technical writers produce comprehensive documentation.

  Writing should be the minimum possible length. Oddly, most students learn this guideline in grade school and have forgotten it by grad school. If a help system must be truly comprehensive, it should be because readers will accept nothing less, which is untrue 99% of the time. Huge blocks of writing look intimidating, and excessive content waters down useful content. Identify what the audience actually needs to know, and include only that.

• Technical writers help protect companies from lawsuits.

  No, lawyers do that, and believe me when I say that they're perfectly comfortable composing their own indecipherable text. Technical writers, at the absolute most, should collate legalese into their websites. You should take content verbatim from actual attorneys and spend no more time on it than it takes to press Ctrl + C and Ctrl + V. Then show them how to update the content themselves so that you can get back to your real job.

• Technical writers produce print documentation.

  Any piece of print documentation should be an absolute minimalist Getting Started guide (complete with requisite legal boilerplate) that directs its recipients to a web page. People are comfortable typing www into a web browser if they need help.

Unfortunately, producing content that people will read and find useful is, like, really hard. Here are the basics.

Don't write often, anyway. Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn't comprise more than 10% of your time. When people say, "I was writing all day," they don't mean they were intermittently typing for eight straight hours. They mean they spent the entire day engaged in the writing process. And a big part of that process is installing, configuring, and testing software. In other words, learning.

Remember, the job of a technical writer is not to find bugs. Sure, you will find bugs, and if you're not aware of any, you probably don't know the product very well. You should also report these bugs to developers. But the main point of a technical writer performing testing is not to improve product quality, but to increase personal knowledge. Your testing should be centered around making you smarter. Once you have a complete grasp of how something works, you can stop. Unlike a tester, you don't have to go any further. You don't have to reproduce tricky issues or check for unforeseen regressions in functionality. This difference makes your testing less tedious and more selfish than that of a formal quality assurance process, but because the ultimate goal is to teach others the material, you can pretend to be an altruist.

Be sure to leverage all the wonderful writing that developers and testers produce, even if it's half-complete, riddled with typos, and on a wiki page entitled "integrating with shamrock =D." Check the source repository for any files named README.md, and run any scripts with the help argument. Google any underlying open source software. Check Wikipedia for unfamiliar terms. Take notes. The learning process is time-consuming, so don't be discouraged if your measurable output is essentially nil for days or even weeks after moving onto a new project.

Contrary to popular belief, there are all kinds of stupid questions, or at least ignorant ones. The goal of all this testing and research is to be mentally equipped to ask pointed, intelligent questions to business development, product development, quality assurance, customer support, and ideally, actual users. For business reasons, this last group might not be accessible, but try your best to get in touch with some of them.