Made by
Made by
Erin McKean
Beautifully crafted documentation takes practice and skill. But, says Google’s Erin McKean in her talk from DevRelCon London 2018, weighing up your words is worth it for the insights, support, and empathy they can deliver.
https://www.youtube.com/watch?v=zPj8krIJNm4
My name is Erin. And a couple of months ago, probably too many months to count, when I was emailing with Matthew about what I would talk about, this is the title that I came up with and I’ve been agonizing over ever since. And I feel like that this talk is kind of tangentially the same talk. I really do want to talk about empathy and documentation and developers, kind of all in the same bolus.
But empathy, we heard a lot about this morning, a really great talk from Leslie, some practical tips to increase your empathy for other human beings of the subtype developer. And empathy is really about understanding the feelings and the desires and the situations of people who are not you.
And I want to focus on having empathy for humans, subtype developers, subtype those who are reading documentation. And my main point is that empathy in documentation is really about one thing, and that one thing is putting the reader first.
And I was thinking about this, and I was thinking about, “Oh, okay. Do you know who else spends a lot of time thinking about the reader and what the reader wants? And those people are novelists.” When we write developer documentation, we have a huge advantage over the novelist in that developers are often reading what we’ve written for extrinsic reasons.
They have to read it. This is not true of most novels published in this century. Right? Unless you were assigned it at school, you’re reading a novel for pleasure. And the minute a book stops being a pleasure, it gets put aside. Because let’s be honest, there is more Netflix at this point than any one human being could ever finish.
And so, you know, the book is put aside the minute it stops being engaging. Or as the joke goes, you know, “This is not a book to be lightly tossed aside. It should be thrown with great force.” And has anyone else in this room also published a novel and written developer documentation? Hey, all right. We’ll talk later because it is very similar.
Because if you think if people on Hacker News can be jerks about stuff that you’ve created, do not read your Goodreads reviews. Even when they’re nice, sometimes they pick up on things that you’re like, “I did not write that for you.” So I’m going to show you a lot of pictures of people reading during this presentation.
Because, first of all, what is the use of a presentation without pictures or conversation? And also because they will help us keep the reader in mind. Anyway, novelists think a lot about writing and also, because they’re writers, they often write about writing. Because honestly, writing about writing is a lot easier than, you know, writing fiction. And their advice is 100% focused on not having their books being thrown aside with great force.
So I started to think about, “Okay. What if instead of getting, you know, a master’s in Fine Arts and, you know, a master’s in Writing, you could get an MFD, a master’s in Fine Documentation and using classic writing advice?” Because writing is hard, and we need all the help we can get. And also, is anybody here doing NaNoWriMo? Like, November is National Novel Writing Month.
It’s also November is National Novel Generating Month. So if you can write a script that can generate 50,000 words that has the approximate shape of a novel, you can also win that contest. It’s a lot of fun. It’s a lot easier than writing 50,000 words of fiction. And anyway, this is probably the first bit of advice that most writers of any kind get, “Show. Don’t tell.”
It’s often attributed to the writer Anton Chekhov: “Don’t tell me the moon is shining. Show me the glint of light on broken glass.” You know, it’s beautiful. That’s evocative. And I made the mistake of going to Quote Investigator, and it turns out he did not say anything…I mean, he said something kind of remotely like that and also, he said it in Russian.
But the general idea was first expressed in that kind of form by Chekhov, and you get the idea. And I also learned my lesson, so I did not Quote Investigate any of the other quotations in this talk. And I think that showing, not telling, is something that is an easy thing for us to do in documentation.
But when you tell instead of show, this is what your readers look like. They are so upset with you. And it’s not that hard to show, rather than to tell. It can be as easy as this – don’t tell people to add their API key. Show them where to put their API key. You would not imagine the number of support emails I have answered over the years until we changed this in our documentation.
I think that you should think of everything in the exposition of your documentation, that is everything that’s not a code sample, as a stage direction. If in your exposition, it says, you know, “Make this call pursued by a bear,” there better be a bear in your code example. They should both be coherent, shown in the same way.
Here’s another piece of writing advice that I think really applies to writing documentation. So your documentation should have an opinion. It should have a point of view. Even if that point of view is as simple as, “Our tool is the best thing to solve your problem,” say that. And I’m not saying that you should definitely try to piss people off.
But trying not to piss people off is a definite losing move if your users, if your readers would be better served by you saying, “This is the way that we think is best.” Because when people are coming to your documentation, it’s because they don’t know something.
And the things that they don’t know are often, “What’s the best way to do this?” And don’t just give them their options and treat them all with equal weight because, in the real world, not everything has equal weight. Give them a giant, flashing sign over their best option. Some people will not like what you write, not because it’s bad, but because they don’t agree with your position.
And that’s okay. I mean, don’t go out of your way to piss people off, but don’t try to be all things to everybody. Something that is for everybody is for nobody. And if you think you don’t have an opinion, if you really think, “Oh, I don’t care what Erin said. These are all perfectly equal options,” start writing. You would be surprised how often an opinion will emerge from your writing process.
If you really don’t know what you think, figure out what some of the possible things are and just try to write something in support of each of the options. And usually, the opinion you care the least about, the thing that you are the least invested in, will have the most weasel words, the most fluff, the most empty sentences that take a really long time to say nothing, because you don’t have enough oomph there to fill it out.
So cut all that out, and then cut that opinion too. That’s the thing that you can get rid of. And getting rid of things is the heart of a lot of writing advice. Does anybody see the problem with this statement? What’s the trap word here? What’s unnecessary?
This is the rabbit hole. All of the work in writing is figuring out what’s not supposed to be there. And this is where technical writers have another advantage over novelists because you can just keep taking things out until your examples don’t work anymore, or until people will like, say, “Huh?” But when you do that as a novelist, you end up with things that are like, this sentence, no verb.
So it takes a while, but you get there. So when we’re thinking about cutting out what’s unnecessary, the legendary crime writer, Elmore Leonard – if you haven’t read any Elmore Leonard, you’re in for a treat – he had some really good advice. This seems very logical – take out the part that people skip.
So what is this in documentation or technical writing? Maybe it’s the history of your project, as fascinating as it is. Maybe it’s the laundry list of reasons as why you are better than your main competing project. In general, readers tend to skip anything that lies between them and the solution to their problem. Now, here’s another place where documentarians have an advantage – the advantage of hyperlinking.
Are there parts that you’re not sure about them? Put them behind a link, see if anybody clicks on them. Nobody clicks on them, you didn’t need it. At your next content review, you can take it right out. This does not work with novels because then people are like, “I don’t understand what just happened.” So in order to empathize with your reader though, in order to figure out what they’re going to click on and what they’re not going to click on, you really have to know who your reader is.
And that could be a whole other talk, trying to figure out who your reader is. But one trap that I think people fall into a lot is, if you’re writing for people who are playing the tambourine, leave out all the parts that have to do with trombones, even if you were a trombonist and you would like all your tambourine players to eventually play the trombone. It’s very hard to write outside of our own perspective, especially when we think that our instrument is the best.
But if you’re writing for beginners, try not to sneak expert-level stuff into them even though you want them to be experts someday. But if everyone waited to be an expert before writing documentation, we would not have any documentation, or we would only have documentation written by extremely overconfident people. I firmly believe that knowing comes from doing and that it’s difficult, if not impossible, to know everything you need to know before you begin.
So you might as well begin today. You know? And I think writing has a magical way of crystalizing your thinking, letting you know where your gaps are, and then helping you fill them. Who here has learned something simultaneously to writing the documentation for it? Yeah. See? Good job.
You’re doing it the right way. It’s especially good if you can remember the tricky parts of what you’ve learned. I recommend keeping a friction log of everything you’ve done and what you tried, and what worked and what blew up into giant, flaming wreckage. Because we tend to have a kind of confirmation bias, where we remember the things that worked and forget the 99 things we tried that did not work. But your readers are going to come to you looking for the solution to one of those 99 things.
And also, you should write more. How much are you writing now? Double it. See how many different ways that you can write something. Eventually, one of them will be the right way. Maybe not the installation limericks, but you never know.
But really, I totally agree with Ray Bradbury here, that from experience alone comes quality. From practice comes experience. And writing is like exercise – if you only do it every once in a while, it feels horrible. If you do it all the time or very frequently, it feels a lot better.
But just because you’re writing documentation, it doesn’t mean you get to stop thinking about how your writing sounds. In fact, the more difficult the subject matter, the more you should worry about the shape of your sentences. Are they tight and crisp, or do they like wander all over the place? Imagine you’re giving someone verbal directions to do something really complicated and slightly dangerous, like driving a backhoe for the first time.
If you read out loud what you wrote to them, are they going to be right there along with you? Or are they going to have to ask you to backtrack, to wait a minute, “Hey, can you say that one more time?” What you want them to be able to do is reverse that backhoe on the first try, and that takes a lot of reading out loud.
Okay. I’m going to go onto a tiny like tangent rant here. Sometimes people think it’s kinder to the reader to use simpler language instead of the technical terms that are used with your product or your field. Now, I have to admit that I am a dictionary editor, so I am biased in favor of using the weird word, the odd word, the technical word, because full employment for dictionary editors if more people look stuff up.
But it is not a kindness to avoid using essential technical terms just because people might not have heard them before. You’re trying to teach people things. You’re trying to get them to that point. Use the terms and either explain them in context, or link to a place where they can be explained. I have some recommendations of places to link to if you would like. But not using the accepted jargon is like talking in baby talk, it is insulting.
It is not empathy, it is condescension. So there are words that we use in our communities and about our technologies for a reason. It’s perfectly okay to use them, even if the general reader would not know them, because you’re taking a person from being a general reader to being someone on the inside who knows the jargon. And your reader doesn’t want perfect. Like, they’re okay with maybe not understanding some things around the edges, or maybe there being a little bit of a gap between Step 2 and Step 3, because something that gets them most of the way there is better than a blank page.
And how many people have actually waited so long to release like a blog post that the technology actually changed and made it obsolete? Yeah. Did that help anybody? That helped nobody. It made you feel miserable. It would have been much better just to put it out there in the world. How many people did you not help?
Who benefits from you not putting that out in the world? Here’s another advantage you have over the novelists is that you can update what you’ve written at any time. When you find a better example, a better analogy, the code changes to become a little more readable, maybe even you just have a better color scheme for your page, you can change it.
If a novelist is lucky, they might someday get a new cover. And maybe it’s going to be a movie tie-in cover, which everybody hates. So another way that fiction writing and documentation writing is very similar, the rewards are fairly amorphous. If you are in fiction writing or documentation writing for the money, may I suggest a course of buying Powerball Lotto tickets.
If you are writing for fame, probably tweeting a picture of yourself, like a little GIF of you falling down the stairs pursued by a kitten would be way more likely to make you famous. Really, the rewards of writing something well tend to be more intrinsic, even when it’s part of our job. Because a lot of people can’t identify good writing versus bad writing, they just have, “Oh, here’s writing that exists versus writing that doesn’t exist.”
So only you, in many cases, will know when you’ve done something well because it’s proving a negative. “We didn’t get a lot of complaints about your last blog post or about this documentation. Great job.” Right? And also, if you think of readers as a means to an end, if you think of them as the wide part of the funnel that leads to the bottom where the dollars are, it will show through in your writing.
It’s hard to keep empathy for the reader in mind, to put their needs first, if you think of them as a means to an end. And if you hate writing, you will grow to hate readers because they are the people who are making you write. If you really hate writing, try to pass that off to somebody else. But good writing gives you a perspective on the world that you didn’t have before, and great writing changes you both as a writer and a reader.
Your goal should be that people should be different after reading what you’ve wrote, and not just 20 minutes older. If you can make people see things in a way that they’ve never seen them before, they will come back again and again to look through your eyes, even if it’s just with documentation.
If your documentation makes people see and feel that something is not only possible but is possible today, by them with the tools that they have right now, they will use your product with joy. And this is just scratching the surface of advice about writing. I think there are almost as many books of writing as there are living writers.
But if there were one universal rule, I think it would be that of empathy, put the readers’ needs first. And if you satisfy the reader, I promise you, everything else will come. Maybe not the fame and fortune part.
So thank you very much. I’m happy to talk to people more about writing. Christiana did say the title of my novel. It is called “The Secret Lives of Dresses.” It is mostly about dresses. Usually, I say tech audiences are not usually my core audience for my fiction, but Walt Mossberg read it, so there you go. He actually liked it, which is probably the best review I ever got. And I do want to thank all the museums that have made their images available as public domain, which is kind of amazing.
If they could only work on their search engines a little bit, everybody would be happy. And, oh, if you want to follow me on Twitter and also on GitHub, I am @emckean. If you see a pink robot, that is me. Accept no substitutes of any other color robots. So thanks again for your kind attention.