 Please make Heidi welcome. Switch. There we go. Hi. Are you all awake still? No. You had some options to get caffeine, so everything else is on you. My name is Heidi Waterhouse. I am a developer advocate at LaunchDarkly, and I'm here to talk to you about technical writing, because that's what I did for 20 years. And I have some opinions. You're in there. So when we use software, we never sit down and say, wow, I wish I could use some software. It's not a thing we enjoy doing. We enjoy doing things with software. But I have yet to meet anybody who's like, you know what I really love? I just love the physicality of writing something in code so that I can use software. It's not what we're doing. We're like, I want to do a thing. I want to climb a mountain. I want to find a leafy on. I want to find an ATM. There's a lot of reasons we use software, but it's not because we like software. Being that we don't have feelings about software, we have a lot of feelings about software, we mostly just don't notice our feelings about software because the emotion's kind of like eh. Or we might notice feeling a little happy if software is particularly well-designed to help us do what we want. But mostly, the emotion that we notice about software is this or like this. Like that's how we feel a lot about software. Every time we notice we're using software, we're a little bit angry because we are not catching our leafy on, right? So that's how we feel whenever we can't do what we were trying to do because we're having an interface. And I want us to be able to get past that by obviously psychically controlling everything in our world. But since we haven't managed that one yet, let's talk about some better things. First, nobody likes reading documentation. They like knowing things that are in documentation sometimes. And I say this with all the authority of somebody who wrote documentation for 20 years because I really hate writing documentation. And it turns out if you're a technical writer, there is no documentation and so you never have to write it or read it. It's so great. Nobody says, did you read the docs? Because you're in charge of making the docs. Yes! But eventually, you know, somebody else makes the docs and then you have to read them. By the time most people go to read documentation, they are already angry because they have already noticed that they are interacting with software and they have already failed to do what it is they wish they were doing. So by the time everybody gets to documentation, they just want their question answered. Like, please do not tell me about the architecture of this. Please do not tell me the origin of your adorable name. I know you think it's funny. I don't care. Like, don't tell me any of that. Just tell me how to do the one thing that I'm trying to do so I can get on with my life. I first formulated this theory almost 15 years ago when I worked for a company called MQ Software and we made a product called QPASA. And the powers that be ordained that all of the bullet points in the 800 pages of documentation were going to be chili peppers because QPASA, get it? No one I ever met in all of the time felt like WebSphere MQ message queuing software was improved by adorable little bullet points. It's not how we improve documentation. So what does make documentation better or at least make it suck less? Getting the exact answer that you want to the question that you're asking. Not having to dick around and ask the question like 14 times is the best way to have documentation. So very few developers like writing documentation because if you did, you would obviously all leave for the green fields and high pay of technical writing. And the people who do like writing documentation are over-represented in this room because you didn't sneak off during coffee break to take a nap. Thank you. So if developers don't really enjoy writing documentation or reading it, why am I giving you this talk? The benefit of documentation is that it saves you from answering questions from irritated people over and over again because you could be like, oh, I put it in the wiki and then they can go read it and you don't have to answer it again. So burnout is a real problem. How many of you use Read the Docs? Excellent. How many of you are paying for Read the Docs? Damn straight. Yes. All the rest of you are having arguments with your companies about this or can't get it to pay, but Read the Docs is essentially run by one and a half people and the one person is Eric Holscher and he also runs amazing technical writing conferences and he's great and he is a crispy burnt out thing and if Read the Docs goes down, there's like a good odds that he will just burn it to the ground and take off for the Pacific Crest Trail. And I can't blame him because he's been answering the same questions over and over and over again for everybody without getting paid a lot of money to do it. And that's pretty regrettable and it made me think about how writing documentation is a way to prevent burnout because it distributes community knowledge to the community. So like Docs, they're not just because you don't wanna answer questions from people but it doesn't hurt. So how do developers write pithy answers to actual problems? Before I answer that question, which I am going to answer, I'm going to give you a pitch. Hire an expert. Do you put in your own window glass? Are you the sort of person who actually like fixes their own transmission by milling parts? Or do you hire experts to do these things? Because I am all for the hire experts to do things that will take me a long time to do. I think maybe it would be more efficient to hire writers that can learn technology rather than taking highly paid developers and making them do something they're mediocre at slowly. Like it's a crazy economic thought I had that maybe it would be more efficient to hire an expert to do something they do well. This argument does not actually make a lot of traction with enterprise customers for reasons that I have never figured out. So if you hire a technical writer, we use all of our magical technical writing tools and our years of experience in education. And we can make your five people in an incubator look enterprise grade. I'm just saying it's a thing you could do. For most technical writers, the pay is or should be equivalent to a Python developer of the same experience and quality. Don't underpay your writers because then you get crappy writers and then you have that feeling like you have to do the whole thing for them and then they just put some commas in it. Call it good. Pay for good writers. Okay, yes. But it's not always a choice you have because it turns out that you are not the boss. You work for the boss and the boss is in charge of the money. So you still need to answer questions about your product. What are you gonna do? You're gonna have to write your own documentation. There's a giant blank page in all of our souls and it haunts us at night. And nobody loves the blank page and we're all just like, the blinking cursor stares back. But I'm gonna tell you how to do this painlessly as possible. First, first, you have to figure out what questions people are actually asking. Not what you think they need to know. Too bad, not a problem. What they are actually asking and stumbling on. And if you don't have users, find some people who are like your users and profile them and ask them what they do and figure out what they're trying to accomplish. And if you don't have users and you don't know who would be like your users, you have a much bigger problem than documentation and you should stop now. Hide from your investors and go figure out what it is you're actually trying to do. Ask your users what they're trying to do with the software. Not how they're trying to do it, but what they're trying to do. What are they trying to accomplish? And you're gonna find out that they are not like you. They have different goals and priorities. It turns out they're not just like projections of our imagination. You're gonna need to watch them try and use your product and bite your fingers so you don't say anything as you watch them do stupid things. Because they're not you and they don't know how it's supposed to work. Watch them use your product without helping them so you know where they're hitting problems. If your product is accessible to the world somehow, find out where your users are talking to each other. When I was a wee baby tech writer, this was a mailing list called Framers L and it had all of the knowledge of the frame maker world including stuff that never appeared in the documentation distilled into a whole bunch of really helpful people who would like answer pretty much any non-stupid question and lots of the stupid ones. If your users can find your product, they're talking to each other someplace and it might be on Stack Overflow and it might be on a bulletin board pinned to the faculty hallway and it might be on an IRC channel. I don't care where it is but find out what they're asking each other, what they're helping each other with because that's gonna give you a really good idea about what the community is trying to accomplish. If you have anybody doing support for your product, first take them cookies and say thank you a lot because they deal with angry people who have not been able to find an ATM all day. And then sit down and genuinely listen to them when they tell you what problems people are having because they are at the very pointy end of the stick and they know far better than you how this is actually going in the world. Collect all of the questions that they get and put them in your question list. Hopefully you have a huge list of questions now. You're like, how can people misunderstand a simple product so often and in so many ways? People are amazing. We're like miracles of misunderstanding simple things. So take that giant list of questions down to 20 questions to work on it first because you cannot tackle the 400 questions. It's just intimidating. It's almost worse than the blank page because fun fact, the normal distribution curve applies to almost everything in the world. So once again, 20% of the effort, 80% of the results. So find 20 questions and answer those and it turns out you're going to cover a vast array of things that people actually care about. And I know you're interested in the weird edge cases, like how does it even happen that way? And it turns out there aren't actually that many people running Raspberry Pi's at all, let alone using Raspberry Pi's to run their 3D printers while controlling them with their Microsoft phones. So don't answer that one first. Like answer the things that people are actually struggling with the most. Do a frequency analysis if you have to feel justified about doing math with this. Now stop and set up some analytics because if you haven't figured out how people are coming to your site and what they're looking for, you're really missing out on this rich vein of information. So you want to know what search terms people are using to get to you and how often people are already getting their answers questions answered without having to call support or complain or whatever else. Like if somebody goes through and gets their question answered by your website, that's a 90% win. 100% win is they never come to your website because the product works. But 90% win, they get their question answered without bothering anybody. And both of those things are really important to take care of because you don't know how else it's gonna work. I use Google Analytics on my personal sort of neglected website and it tells me some important things even though I don't have it configured hardly at all. It tells me what people are reading. I should write more things like that. It tells me what people are bouncing off of. I should maybe not write so many of those. It tells me where people are coming from. I love you all, the 20 dedicated readers that I do have. And it tells me what people are searching on and looking for in my site and trying to find. All of those things are pretty actionable for me. I can make things better by knowing that. So now you have 20 questions. Answer those questions in a way that people can find and use. You need to make sure you're answering the question they actually asked as opposed to the question that you got. Anyone who has worked in tech support understands that humans are remarkably bad at actually defining their problems, right? They're like, well, my computer doesn't work. Yeah, okay, so tell me about how it doesn't work. Well, it doesn't turn on. It took me 20 minutes to establish that this person was unclear on the difference between computer and monitor. I was not very good at tech support at this point. I should have figured that out a lot sooner, but they were asking the question as best they could. My computer doesn't work. And I was answering it from a place of privilege where I know a server and a monitor are different. So that interaction tells me that my consumers, my users, my callers are really unsophisticated. Okay, I need to know that. I need to say, this is the monitor. This is the server. Tell me which one of those is broken. You also need to be able to test your answers to make sure that you're giving them good advice. Like don't just like answer off the top of your head and then carry on with your day because you will not always be right. Indexing is not the same as search. You need to make your answers findable. And it turns out that what people call things and what companies call things are entirely different sometimes. So what do we all call this? Right, I think so too. For years and years, Microsoft's website did not have the phrase blue screen of death on it. They called it a fatal exception. And even internally, like they would verbally call it a blue screen of death, but if you searched Microsoft's site for the phrase blue screen of death, no, that never happens. I don't, it's so weird. We don't even have a search term for it. It's not very helpful. They do, by the way, now have an index term for blue screen of death, but you need to figure out what your users call things, not what you call things, because otherwise you're not gonna help them. So many times search engine optimization feels like a scam, like we're doing the 1998 trick where we're stuffing meta tags in pages like cynically. I had that job. I knew HTML, I was like a god. But it turns out that we can use search engine optimization tricks and things to help people understand how we could help them more. So this is my road ID. It has my name and phone number and contact information for my loved ones in case I get smeared to a thin red paste because I'm a cyclist. And it's super useful for me because wallets and spandex are not compatible. Don't try it. But there are other people who would also be helped out by things where wallets are not super useful, like sailboats. So even though this is designed and marketed to cyclists and runners, there's nothing that says you can't add SEO editions for wallet and sailing and other kinds of sports that have something to do with not wanting your wallet with you but wanting your body to be identifiable. It works because you're thinking about how the user can and should use things or might use things in addition to how you are marketing and thinking of it. It's kind of important. All right, hands up if you can. Not yet, hang on. Who loves the giant unordered FAQ? Okay, you weirdos. I'm noting you down for later. Who believes that they are actually frequently asked questions? Yeah, I don't know about these guys. I think they are just things that people don't know how to sort. You're like, I should tell people about this. Where should I put it? FAQ, it's not an FAQ. But who searches the FAQ and the futile hope that they might actually get an answer for a weird thing they haven't been able to find everywhere else? Yeah, right? Because it's like the answer of last resort. So we're gonna keep having FAQs and I'm not gonna win this fight about renaming them because this is now like seared into our souls. It's a cop out but you also have an opportunity to use it. If you group your FAQ answers in a way that makes them logically, internally consistent, you're really helping people out. So I am a freak in that I typed Dvorak. And, yeah. And some places, some computer systems think of it as a language and some of them think of it as a keyboard layout. And if you put those together, I would be able to find which one it was because I was searching down the list for keyboard layout and I found languages, Dvorak. I'm like, oh, okay. So spend a little time un-chaoticking your FAQ and you're giving people a lot of information about what things are related to each other. It doesn't do any good. To make something findable, if it doesn't exist, it turns out. I tried to play hide and go seek with my kids this way for a long time and go search for your invisible friend. But sadly, they caught on very fast. So you're gonna have to write a thing and you're staring at the cursor and the cursor stares back and you stare at the cursor and the cursor blinks aggressively. All right, here is the fastest possible lesson on technical writing. I call this minimum viable documentation because I talk to a lot of Agile nerds. First, figure out where you are. You can't tell anybody how to get to someplace if you don't know where you are. So if users are coming to a single page because of search, that page has to tell them everything they need to know. If you need prerequisites, there better be a thing that says you need these prerequisites before you run this function. If there's something you're gonna have to do afterwards to activate it, you better put that on the page because they're not coming to this through a table of contents. It is the future and Google is our Lord and Master. We have searched for the answer and this is the only page we are ever going to go to. So you have to put it all on the page somewhere. An installation page might say, follow these steps after you complete these prerequisites link. I think of this as the game where in the world is Carmen Sandiego? You could go to Sri Lanka all you wanted, but if you hadn't been to the cities you needed as prerequisites, it didn't do you any good. You couldn't find the clue. You have to tell people where the clues are before they can use what's next. Give orders. Technically, we call this the imperative or the second person implied subject. And that's about as much grammar as I know because I care a lot more about language than grammar. But you can think of it as like dictatorial cats. I have a dictatorial cat named Director Fury. Her entire vocabulary consists of meow. This is not her. This is a cuter cat than Fury. Grammar doesn't matter. What matters is stripping all of the politeness and ambiguity out of your instructions because it's terrible for people who are not speaking your language and it's terrible for people who are worried about doing the wrong thing. If there are any if then else statements in your technical documentation, stop and rewrite it because you're screwing people up because they're trying to hold this state machine in their head about what they're supposed to execute on next is not how we wanna do documentation. Just raise your hand or please lift your hand in the air. See I primed you and it still takes longer to do this. Just tell people what they have to do. We are not here to be polite in technical documentation. How does a user know they got a procedure correct? Write a unit test for it. Put the results of the unit test at the bottom of the procedure. So step, step, step, step. You can now, if you don't have a way to say you can now do this thing, what you have written is not a procedure, it's a hypothesis. You have to be able to end a procedure with a conclusion that says the state of this system has changed in a way you can check. Write a unit test for every piece of documentation. Every task has to be testable. Install, test it. Do you have the things there? Is there a directory? Can you access it? Configuration, testable. If you can't think of a test, keep working on it because you're not ready to write this procedure. It's really easy to take things apart, but it's harder to tell if you got them back together correctly. So once you've answered somebody's question, that's great. But this is your one chance to help them a little bit more. This is your one chance to say, okay, you've completed installation and configuration. Your email is set up correctly. Click here to enable two-factor authentication. Right? Click here to enable two-factor authentication because we have them now in this moment. We have guided them through an arcane procedure of maybe five or six steps. We've tested it. We feel accomplishment. At this moment, they're psychologically vulnerable to yet more dictates about how to set up a better system. And you've all had that feeling where you're like, you get through a really long procedure. You're like, did it work? Did it work? It worked. If somebody told you right then that what you really needed to do was save your configuration file, you would actually remember to save your configuration file. But no, we just assume you're gonna remember to do that. Thanks. Not everyone is going to click the next step, but it does give a sequence and a through-flow to your documents. Sometimes there are a lot of procedures to get something going. You and your packages, people. And so even if somebody enters randomly in the middle, you're giving them some guidance on what came before and what comes after. The important part about giving people information is remembering, once again, they don't want to be here using software. They want to get something done. There are a lot more users than there are of us. So do everything that you can to let them own the experience. Let them drive it. Let them call it a blue screen of death. Let them do whatever they want as long as they feel empowered. And like your software, it's going to let them get on with their lives. So what I'm saying is, give the people what they need, give it to them when they need it, let them know how it worked and tell them what to do next. Right, you good? Okay, we're gonna summarize. If this was too long and you read Twitter, answer actual user questions as simply as you can, make it easy to find the answers. Here is a bibliography of books that affected this talk. These are all amazing and you should read them and treasure them in your heart, except Art of Indexing, you can return that to the library. It's both expensive and a little arcane. And if you would like a T-shirt from my fabulous organization, take a picture of the screen and fill in the form and we will send you one because I refuse to carry around T-shirts. So thank you all very much for your time and attention and listening to me talk about technical documentation. And if you want to ask me any questions, you'll be able to find me. Thank you. All right, thank you, Heidi.