The Art of Writing Defensive Documentation
Always write as if your reader is lazy, stupid, and mean… My 9th grade English teacher gave me that piece of advice nearly twenty years ago, and it has shaped the way I’ve thought about writing ever since.
Let’s face it, most documentation sucks. It’s either too technical to be understood, too nuanced to be trusted, or too disorganized to be usable — assuming it’s even accurate to begin with. But it’s hard to blame the authors. While a fair amount of documentation is written by professional technical writers, a not-insignificant amount of it is written by developers simply looking to improve the adoption and usability of their own products.
The Lazy Reader
Early writing education is filled with rules. From how many sentences belong in a paragraph, to how to structure a paper, many of these rules give students a solid foundation of good habits to build upon as their experience grows. But not every rule breeds a better writer. Page limits, the bane of every student’s existence, have bred in us a tendency to fill our work with filler words and meaningless bullshit, all so we can eek out an extra half page to make the mark.
Documentation does not benefit from verbosity.
The more you ramble on, the less likely your readers will know what is important, and what isn’t. In fact, they may bail altogether in favor of a product with more succinct documentation. The Lazy Reader doesn’t care about your life story, so get to the damn point.
The Stupid Reader
Everyone likes to sound smart, and even the people who don’t can’t help but use their language in their product documentation. Buzzwords, industry jargon, proprietary phrases… without context or expertise, these things barely hold any meaning.
Documentation should be easy to read, and avoid making assumptions about a reader’s experience level.
Always remember that high-quality technical content is judged on its ability to simplify complex information. If your readers already understood the nuances of your product, then they wouldn’t need to consult your documentation to begin with. The Stupid Reader doesn’t care how smart you think they are, so keep it simple, stupid.
The Mean Reader
In writing, ambiguity is a sin. In documentation, it’s a killer. While getting to the point and using common language is a great place to start, you should always be on the look out for unclear phrasing. It doesn’t matter how nicely something reads if it can be interpreted in more than one way.
Documentation should be aggressively clear.
When it comes to technical content, clarity can be the difference between success and failure. Sending your reader down the wrong path could imply a lack of quality within your product itself, and ultimately send them to something that’s a little easier to understand. The Mean Reader doesn’t care how eloquent your prose is, so cut the shit.
Embrace the Lazy, Stupid, and Mean
A lesson in avoiding unnecessary complexity, “lazy, stupid, and mean” has become something of a mantra of mine as I’ve grown into my own as a writer. If you’ve been paying attention, it’s not really about the reader at all, but about our assumptions as writers, and the bad habits we all build up along the way. So get to the damn point, keep it simple, and cut the shit. Your readers will thank you for it.
Originally published at https://medium.com/@zachflower/lazy-stupid-and-mean-6b183426e152 on April 10, 2020.