I’ll be honest. I’m a little mad I didn’t write this book. It’s clear, lucid, and pithy. I agree with much of the philosophy of minimal tooling and semantic separation of form and content.
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.
To which I say, yes, yes! I’ve been saying, speaking, thinking, writing the same message. It’s so much more efficient to have good docs. I also agree that good technical writing (about software) is mostly about testing and research, and the time spent with the product should get distilled down into an understanding and then and only then transmuted into words.
He also says that it is much easier to answer the how of software, rather than the why, but you must answer the why to really write something useful. His points on lightweight markdown, rapid publishing, and internationalization are all exactly on-point.
My quibble with this book (and it is only a quibble, not a full-fledged criticism) is that there is a section missing, and it is the section on user motivation. You can write the most beautiful, terse, lightweight, well-indexed documentation in the world, but if you’re not driving toward what the user needs in every sentence, they’re not going to read it. The user doesn’t want to be reading documentation. Reading documentation is the opposite of doing something interesting with software. It’s filling up the car before an amazing road trip, it’s an impediment. And until we as writers realize that, we’re going to continue to write too much, for the wrong people, at the wrong time.
Etter is very clear up front that this is only about software documentation, as practiced in software companies. But there are a lot of people in technology, the majority of people in technology who don’t work building software per se.
It’s not Etter’s fault that we forget this. We have build ourselves a cozy little ecosystem, and if I told you I worked for a company doing Hadoop or containerization or financial APIs, you would understand that I worked for a software company. But I have also worked for a health insurer, a social media empire, a durable goods manufacturer, a commodities broker. I wrote about software, I wrote about our products, I made decisions about security and metadata and the location of quick start guides – as a technical writer. There’s a big non-software world out there that we keep forgetting to talk to and learn from.
What would this book look like if we didn’t assume that software was a service, that our users were relatively computer-savvy, that we were not the only kind of writers in the world? I keep coming back to this article by the Nielsen Norman Group: The Distribution of Users’ Computer Skills: Worse Than You Think. Jakob Nielsen, trenchant and brilliant as usual, points out that we keep designing things for ourselves, and we are really, terribly, fearsomely wrong about that.
You = Top 5%–8%
The main point I want to make is that you, dear reader, are almost certainly in the top category of computer skills, level 3. In the United States, only 5% of the population has these high computer skills. In Australia and the UK 6% are at this level; in Canada and across Northern Europe the number increases to 7%; Singapore and Japan are even better with a level-3 percentage of 8%.
Overall, people with strong technology skills make up a 5–8% sliver of their country’s population, whatever rich country they may be coming from. Go back to the OECD’s definition of the level-3 skills, quoted above. Consider defining your goals based on implicit criteria. Or overcoming unexpected outcomes and impasses while using the computer. Or evaluating the relevance and reliability of information in order to discard distractors. Do these sound like something you are capable of? Of course they do.
What’s important is to remember that 95% of the population in the United States (93% in Northern Europe; 92% in rich Asia) cannot do these things.
You can do it; 92%–95% of the population can’t.
What does this simple fact tell us? You are not the user, unless you’re designing for an elite audience. (And even if you do target, say, a B2B audience of nothing but engineers, they still know much less about your specific product than you do, so you’re still not the user.)
I’ve seen people take this argument and assume that means we need to produce more videos, and I think that’s the wrong assumption. I think that what Etter, and I, and you, need to do is remember that the world is bigger than “software development” and writing for the people in the big world is the next level, something we have to strive for, rather than staying in our small and shrinking tidepool of high-tech and software.
O'Reilly Software Architecture/Velocity
The Lead Developer London
Full Stack Conference London
Texas Scalability Summit