: New: Book Report: The Art of Explanation

I'm a tech writer. "Professional Ignoramus" would be a more accurate job title, albeit not so likely to land me fun jobs working with clever software developers. Still, it's what I do. Here's what happens:

Clever software developers put together something useful. As they make this thing they become experts on this thing. Now they want to convince other software-makers to use this thing. They need to make its benefit clear. But they're experts and now they need to explain it to non-experts. This is surprisingly hard.

Experts "explaining" stuff to novices often fail. They use jargon that novices don't know. They jump from Point A to Point C while forgetting to mention the Point B between them—they don't omit it on purpose, they just forgot that the explanation doesn't make sense without that point.

So I come along and ask the experts to explain themselves to me, the professional ignoramus. And when they don't make sense, when they leave out skip something important, I don't roll my eyes and give up. Instead, I note down things that I bet will be unclear to non-experts. Then I research those things, write them up, and add them to the documentation.

The Art of Explanation describes this process. I guess. I kinda skimmed it. Look, when it comes to explaining things, I'm one of those boring experts who agonizes over nuance instead of remembering what it was like to not know the basics. This book is aimed at novice explain-ers. There were probably some nuggets in there I could use, but my eyes glazed over pretty early, slogging through the basics. That doesn't mean it's a bad book. I bet it's pretty good for its intended audience.

Tags: book writing

blog comments powered by Disqus