Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Background Recently to try to get better sleep, I switched from reading my iPhone at night to a Kindle E-reader. It turns out I really like reading from the Kindle E-reader, so much that I actually bought two of them (the Paperwhite and the Voyager). Reading from the Kindle feels more offline, so I can get immersed more fully in the content, rather than flipping back and forth between email, Reddit, Twitter, or other sites. While reading on my Kindle, I stumbled across a book called Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter, published in 2016. It’s is actually a short book (10,000 words), and you can read it about a half hour. Modern Technical Writing, by Andrew Etter Who is Andrew Etter? He provides almost no biographical details about himself in the book, but based on my Linkedin search, he seems to be a lead writer at Palantir, which is a company in the Bay area that I actually toured when I moved out here. Andrew’s book should be required reading for every technical writer, both experienced and novice. I’ve never felt more at home reading a tech comm book than I have with Modern Technical Writing. Admittedly the book is short, but this is good. It means he doesn’t pad it with extra fluff to achieve a book-length word count. He jumps straight to the point and writes with such an easy-to-follow, conversational voice that I couldn’t help but just like the guy. What does it mean to do “modern” technical writing? From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code. Etter also argues that writers should spend most of their time researching and testing content, investigating analytics, and iterating on the doc content on their websites. Contributors and lightweight markup languages With regards to documentation formats, Etter writes: … one of the tenets of modern technical writing is that everyone is a contributor. Storing content directly in XML-based languages like XHTML, DocBook, and DITA dramatically reduces people’s ability to contribute…. Rather than being mere deterrents (like writing in XML), specialized applications actually prevent people from contributing. Amazing text editors are available on every operating system, mostly for free, and writers can use whichever they like. … For documentation, lightweight markup is free and superior in every meaningful way. Etter compares a simple passage in written in AsciiDoc with the same passage in Docbook. The Docbook passage is about about 7 times longer than the AsciiDoc passage and contains so many nested tags it’s nearly unreadable. Rather than embrace the lightweight formats for simplicity, Etter says technical writers need to encourage contributions from those who have deep, helpful product knowledge. He says, The reality of the profession is that even a large team of writers cannot possibly know everything worth knowing about an application, and most companies do not have a large technical writing team. The open-source software movement, mod scene in PC games, and birth of a million obscure wikis have proven that people will happily share their expertise and passion if an easy, hospitable way of doing so exists. Static site generators Etter also advocates using static site generators for documentation platforms, especially Sphinx because it has built-in search and sidebar navigation. Etter devotes a good part of the book to static site generators, explaining: I have perhaps an irrational bias towards static websites. I love them. I love their speed, simplicity, portability, and security. You can host static websites practically anywhere…. They have no server-side application dependencies, no databases, and nothing to install, so migrating the entire site is as easy as movi