 Okay, we're good. It's 11.30, so I'm going to start in time because I do have a lot of stuff, and maybe the bus is late. There's seven rules for world class technical documentation. In case you don't know it, this is like an exclusive club, so we're going to close the door in a minute and nobody else will be able to come in, and that'll be it. So this is Jules. He's the production manager. This is a job you have to work your way up to, and we're great. So let's do a little run here. Let's hit the space bar. Boom. So here's what we are. There you go. Jules rocks, right? Okay, so what you'll be able to do at the end of this, we're going to do, who are you, who am I? Why am I here? The big existential question of all time, why am I here? And then I'm going to talk about defining world class technical documentation. The seven rules are real-world examples, and I'm going to spend a lot of time on video. Now, I've done this like a lot. How many of you people have seen this show before? Okay, I have one person. He's the plant at the back. He's actually the reviewer from Hollywood Reporter. All right, so here's what I'm not here to tell you. I'm not here to tell you about how to put a technical documentation infrastructure in your organization. That's another talk. And I'm going to be spending a lot of time talking about content and content creation at a very granular level, because I've learned some things over the years that I want to share with you. So let's, well, Jules, there you go. Okay, so when this is over, you're going to be able to make documentation that's easier to understand, more engaging, and becomes more accurate over time and clearer in purpose. Okay, which is good technical documentation. Jules, boom. Okay, so who are you? How many people are here? Let's do a writing technical documentation as part of their job. Creating technical documentation, none at all. Okay, remember the first slide. Oh, did you forget the first slide? Jules, go back. Go back, first slide. All right, so let's try again. How many of you people are doing technical documentation as a way of life? All right, there is a firing squad. All right, okay, keep going down. All right, go back. Okay. How many people like it? Like, this is really cool. I can't wait to do this. Nobody likes it. All right, how many people hate it? I don't wish I could ever do this again. All right, all right. All right, I'm sorry. What can I say? Nobody liked what's happened till everybody started using it, I guess. All right, so next one. All right, that's who I am. This isn't actually an older shot. This is when I was really adorable before I became moderately adorable. So hit the spacebar, please. Okay, that's Buddha up there. My Buddha tells me, you know, you are not your things, right? Because they're all, and then hit the spacebar. All right, and then Santa Claus tells me I am my things. All right, okay, then Santa Claus tells me I am my things. Hit the spacebar. All right, and my dog is in a gang, and this is my dog. I cheat a dog. And I cheat a dog that goes with me everywhere I go. And this is, most of this is taken on. This is my toothbrush. It's very important that you know about my toothbrush. Because if you're going to write good technical documentation, you need to have clean teeth. I'm going to do that right now. Next. All right, hit it. Well, that's a shot. I've been writing a lot. I've been writing since really professionally since 1994. So that makes me almost old. And so I've been doing this stuff. And I didn't make this up. I didn't have this epiphany about how to write. People taught me, and these were really a breed of person that no longer exists in the world. I need to share this with you. And the breed of person that no longer exists is called a technical editor. They've been eliminated pretty much from our landscape. That and pretty soon, driving cars. And we're paying a price. I'm going to talk about the price we're paying in a minute. So I learned a lot of stuff from these people. They were ruthless with me. They were just brutal. But they taught me how to write technical documentation. Next. All right, so here's a dirty little secret. Hit the dirty little secret. Go on. It's all hard, even the easy stuff. Even the easy stuff is hard. And what do I mean by that? So what I'm going to do, hit it again. All right, so let's take a look at this piece of technical documentation. I have to read from the screen. And what it says, throughout most of the years, when silver dollars and smaller denominations were minted in actual silver, the mint value of the silver was substantially less than their face value. As a result, the monetary value is based on government fiat rather than the commodity value of their contents. And this became especially true following the huge silver strikes in the west, which further depressed the silver price. From that time on until the early 1960s, the silver in the United States dimes, quarters, half, and silver dollars was worth only a fraction of their face value. Oh, that's a lot of language. That's a lot of language, isn't it? So what do you got? You got value. You got all this stuff talking about value. Hit it again, Jules. You got stuff talking about, once more, a relationship which you got to know to play. Once more, oh, okay, hit it again. Go ahead. Okay, he's doing a great job as a production manager, isn't he? All right, good. All right, so here's the deal. So we've read this big pile of words. There probably was about 120 words in there, and there's four different definitions of value, intrinsic in there, explicit and intrinsic, explicit in there. So you got to know what those mean. If you don't know what those mean, you're not going to understand what's going on. Hit it again. Now you have a relationship that you have to understand. The depressed, the price of silver and the huge silver strikes, you got to understand that. If you don't, you don't even get the passage. Next one, all right, and government fiat. Here's what government fiat means. I will tell you this right now. Hit it, Jules. Boom, it's a car. All right, because that's what the reader thinks. This is a car about the government. Go on. Next slide. All right, so what is world-class technical documentation? It is increasingly accurate. It is engaging, purposeful, and here's the kicker, friends. It's easy to understand. If you don't understand what you're reading, I'll let you in on it right now. It's not your fault. It's not your fault. Remember goodwill hunting? It's not your fault. What do you take? I'll take the wrench. Oh, I usually take the belt. That's what most technical documentation is. Do I get to choose the wrench? Or do I get to choose the belt? All right, next. All right, so here's the seven rules. And those of you that have seen it before, I have changed. It is not what's in the article. I've seen the light. Rule number one, if you don't want to read it, don't write it. Rule number two, don't confuse and don't abuse. Rule number three, before you start, be very clear about what you want your reader to do when you end. Next, write to an outline, always. Not sometimes, always. Next, clarity equals illustrations plus words. Six, watch the pronouns. Seven, embrace revision. Everyone go home now. All right, keep going. Next. If you don't want to read it, this used to be, I'll let you in on a secret. I changed this one this week. It used to be dry stocks, but I changed it. And here's what I've come to understand. There really is no individual prescription for how to write interesting technical documentation. Every human being is different. Everybody thinks differently in all that good stuff. But what is important is that it has meaning to the reader and the writer. So here's a trick I've learned. I can, if I had to say one prescription about how to write better technical documentation, is after you write something, read it. And if you don't like what you've written, rewrite it. I mean, it sounds sort of trivial, but it really is important. If you don't want to read it, nobody else will. Or you will become either the wrench or the belt. How many people here have seen Goodwill Hunting? Okay, for those of you who haven't, there's a part where he's talking about his abuse from childhood and both the Robin Williams character and the Matt Damon character abuse his children. They're looking at the abuse and they say, well, which one did you like? And they had a choice between being beaten with a wrench and being beaten with a belt. And Matt Damon says, well, I took the belt. And Robin Williams says, no, I took the wrench. So we don't want to be the wrenches and the belts. But that's it. If you don't want to read it, don't write it. Next, don't confuse and don't abuse. Here's the deal in life. And I'm even struggling with it now. In your pocket, you had this thing that is probably more important than me or I will ever be. It's called your cell phone that has a connection to the web. So the minute I become boring to you, guess what's going to happen? And you're on Facebook saying this guy's boring or you're on... I just heard about WhatsApp. But you'll be on WhatsApp messaging or that. This is our landscape. This is our life. And we're constantly battling it. So the minute you confuse a reader, and a reader, I don't mean a textual reader because I'm going to talk more about media in a bit. The minute you confuse somebody, you're gone. They're gone away. They're never coming back. So you have to be very clear to keep their attention. And the best way to lose their attention is to confuse them. Do not confuse. Do not abuse. Next. So what does that mean? Use graphics, examples, analogies. Here's the biggest one. Here's the biggest confusion point I've seen in my years of doing this. It's using the same word to mean have different meanings. Going back to remember that thing of value, we had four different meanings for value. And like what is this guy talking about? So use the jack to jack up your car. You got me. Right? Use the noun to do verb or use the jack to elevate a car. If you found and redone it, the thesaurus really is your friend. If you find you're using the same word twice with different meanings in the sentence, don't. Don't. But that's English 101. Next. All right. So the other one is when you're writing, be very clear of what you want your reader to do when you end. All right. This is not a novel. There's no mystery here. You want to be very clear about the subsequent behavior. You're creating a contract with your reader. And when you create a contract with your reader, you're making a promise, and you need to fulfill that promise. So let them know. Like, I promise I will teach you how to make chocolate chip cookies. I mean, the cookbook really is our friend. It's probably the best technical documentation around because they got to sell them. And they just tend to sell a lot of them. Cooks that don't work don't get sold. All right. So the big one is to be very clear about what you want your reader to do at your end and state it upfront. Next. All right. So the other one is I call the three rep rule. If you're doing particularly complex documentation, one rep doesn't work. I used to be, I used to do work with the Iowa school system. And they did a study because they're very concerned, you know, the Iowa basic skills test, remember that thing? The destruction of mankind. Anyway, what they would do is they found out that really, really bright kids needed a minimum of three repetitions to understand what was going on. And at the other end of the spectrum, it was 11. And they designed the curriculum and the classes accordingly. So given that anybody that's ever done any sales, you know, tell them what you're going to tell them. Tell them and tell them what you told them. That really does hold true. It's really hard to pull off writing a piece of documentation that has meaning and value unless you do the three reps. And that can take many ways. I'm going to show you this, particularly around a methodology I use. Next. Okay. Right to the outline always. How many people remember right to an outline here? Oh, good. Oh, all right. Okay, that's really, really good. This is an outline. And I'm going to discuss the rules of outlining very briefly for those that you need to refresh it. It's an outline. Okay, hit it again, Jules. All right. Okay, outline. You might not see the outline, but you can see that the format, the rendering has changed, but the outline remains the same. The rendering has changed, but the outline remains the same. Next. Okay. Oh, hit it again. Now, there you go. And this is, you know, modern, but if you see, there's the outline. There's the outline for the U.S. Constitution. Now, what's interesting to understand here is the basic rules of outlining, and most people don't. I've seen a lot of documentation where people will put network, network, and then they'll do network connectivity, and then network security underneath it, right? And you'll have some copy about network connectivity, and some copy about network security, and nothing under network. Okay. And that violates the two sentence rule, which I'm going to talk about in a minute. But you never have a descendant child with only one item, and there's a logical reason for that, and I'm going to go into it in a minute. The rules of outlining are you have a root, and then you have subordinate children, and then underneath each subordinate child you have at least two entries. So if you have root one entry, that's illogical and illegal. You'd only have root. Now, I'm going to go over it again. Next. All right. So, again, I just discussed this. The two sentence rule, which is very important, and it's taught to me at McMillan, is that if you have a root portion in your outline, you have to have at least two sentences in that section. And if you don't have two sentences, you don't have an outline node, and that's standard publishing stuff. Now, you might say, and this is anecdotal, but I'll share it with you nonetheless, why do we care about this stuff? Well, in the old days, when books were published in paper, and even though we're seeing research in some paper, it's nothing like what's happening on a line, is that the way you determined the price that you were going to sell the book at was based on what's called its paper count. Okay, if a book had 500 pages, that paper costs money plus the production costs. And what you do is an author, when you prepare a book, very few technical writers get asked to write books. You have to make a pitch. And the pitch is you provide an outline, the typical rule at that time, with an outline to the third level, and you provide a page count at every root node. So that would mean my book title, Chapter 1, Page Count 30, Chapter 2, Page Count 40, Chapter 3, Page Count 50. So what that means is at the end, you say, oh, this is a 360-page book. I can now charge $49.95 from it and make a profit. Okay, those days have gone away, and what we have now is we have unbridled publishing, which we're paying a price for, and I'm going to talk about that in a minute, too. So remember the two-sentence rule. Every entry point has at least two sentences. Next. All right, so this, let's talk about that good dog, bad dog. On the left here, you can see we have a bad dog. There's a bad dog. You see him? You see it's a single entry point? Okay, that's a bad dog. So hit it. All right, you can see over here, we have the good dog. And if you look closely, it says, know about the file system of the web. The web should have meaning. What this is really about, what they're saying, is because there's only one node, it really is know about the file system of the web app, is really a child of the entry point above it. Okay, and it takes a little finesse to get used to it, but the kicker is, if you ever find you have what's called an orphan, you're creating a little havoc for yourself. How many people here are writing more than, like say, 3,000 words, a documentation that runs more than 3,000 words? Okay, that's a lot. Generally, okay, 3,000 word people, this is going to hit you. This is going to hit you. 120 word people. New York Times Sunday Magazine section is 10,000 words. All right, a typical newspaper article is probably 150 words, just to give you some sense. All right, but be aware. Next. Okay, clarity equals initial. Okay, you've got to be very careful with your production. Production manager, this is very important. Okay, hit it. Okay, illustrations describe the feeling and words describe the context. Okay, and I'm going to spend, I'm going to go into now illustration. What I've found is that people, for better or worse, have stopped reading text. The way it works for me is that most people will focus, when they come to a piece of difficult documentation, they will look at the diagrams, listings, or code. Typically, developers hit code. I think I'm going to be presumptuous to say engineers probably hit the diagrams. System people hit the diagrams. And their eyes are going to hit those points and then they're going to start reading around it. They're going to start reading around it. So you need to be, now you don't need to do anything. I've become very clear about the immense power of pictures. The immense power of pictures. And getting a sense of what how to make pictures is a very useful and desirable skill. So let's talk about this. Hitted production manager. Okay, this is, let's say the link tastes great. Is this guy, how many agonies do we have out there? Is this guy an agony? Okay. How many ecstasies? How many people just don't care? Okay. I just go, okay. So we've got a lot of agonies, right? And we've got some ecstasies, right? A lot of agonies, some ecstasies. Okay, hit it. Hit it. Boom. All right. Here's, now there's a couple points here. But do you see how powerful that caption now becomes? And I'll let you on a secret. I was writing for a publication. And generally when I'm writing for a publication, I don't fight back anymore. I don't know. I used to fight back. Now I don't fight back. I don't know. I'll make a guitar. I don't care. Anyway, so the publication said, oh, it's all right. We don't need captions. We'll just tell them in the copy to go look at the picture. Well, you're assuming they're reading the copy. And guess what? They're not. They're not. So captioning is a critical piece of technical documentation. People will look at the pictures, code, listings, probably code and listings, and then they read the caption. That's been my observation. So let's do next. So let's do another experiment. Ready? Pay attention. Hit it. Hit it again. Okay, quick. Hit it. Okay. What was that about? Okay. Once more. Hit it. Oh, no. Go up. Go up. Hit the up arrows. Up. Once more. Once more. Once more. Okay. Go hit it again. Hit it again. Come on. This is a good review. Don't worry. Okay. Hit it again. Hit it again. Okay. What's it about now? Yeah. That's big news. That's big news. In New York Times in 1860 came into our world today, they probably jump. You know? Like, what do you mean you don't read? Okay. Next. And actually, have you noticed how much of a language, if you read Ken Burns, remember Ken Burns, the Civil War, this very eloquent, beautiful language they used to talk, just some soldier in the street, and they were just scribing the horror or the missing around them in these very inspiring ways. And now it's like, he's got shot. Anyway. Okay. Hit it. Hit it. Hit it. Okay. Hit it again. What is that about? Okay. Next. Okay. So I've just, this is what I've been talking about. See if I want to take a picture of it. This is, I send the slides in, so they're immediately available. But that's the deal. Pictures, pictures, pictures. Pictures. Pictures. And more pictures. All right. Now, what I do, if I, again, I'm, I'm, I'm, I'm, if I, again, I'm, Jules has been a production manager, so I have no idea what's coming. I have no idea what's happening. But here's the deal. What I do, my writing style, is that I do my outline first, and then I drop my captions, my code, and my listings. Or listings or code, and I drop anything that has to do that's not about text. Pictures, captions, code, and listings. Or lists, if I have lists of things. Then I write around that. It's very rare for me to just write. I don't do it. But that's me. All right. Let's move. All right. So let's talk about creating context. And I've become, those, this is my, here's my commercial announcement. We're all friends now. Nobody's left immediately. Is I do publish a cartoon. That's everywhere. It's called The World In Which We Live.com. Want to help a brother out? Go to the website, The World In Which We Live.com. Get on the list. Get a cartoon every week. Your life will be better. All right. But I've been spending a lot, when we write a cartoon, and we are, we're writing close to two or three cartoons a day now. We really have to begin to understand about visual communication. Particularly if you want to keep the customers and keep the readership. So what I've come to discover is that the wonderful thing about cartooning is that you have to give a lot of information and a lot of context very, very quickly. Because the don't confuse and don't abuse thing is really in line. If they don't get it, they move on. So let's take a look at this. And this is relevant to what we're talking about. Hit it. So let's, this is some guy. This is some guy. All right. Some guy. And what do we know about this guy? Well, let me, how many people think of these happy? Let's do, because remember feeling pictures transmit feelings. They don't transmit context. And this is about the detail of illustration. And I'm going to get, talk more about this. How many happy? Nobody? Okay. How many mad? Anybody think he's mad? Okay. Anybody think, anybody care? Okay. I don't care. All right. We'll give you one more. How many think he's frustrated? Yeah. There's a question. And I will bet. Here's, I have a suspicion in your brain of why you think he's frustrated. And I'm not going to tell you right away, but I'm going to tell you in a minute. But let's throw. Now we have some feeling frustration, but we have no context. Right? Right? We have no context. We don't know what he's frustrated about. I don't know what he's frustrated about. No idea whatsoever. Hit it. Jules. Well. Okay. Am I resonating for you all? I don't want to make sure. Am I resonating? All right. Cool. I'm resonating. It's very important to me that I resonate. All right. Very important. All right. But now let's change the context. All right. Hit it. Go. Well, sort of. But he's really frustrated about ruling. Is frustration an appropriate emotion for that statement? Is it? Frustration. I mean, I will. I'm like, what do you mean? That frustration is not really good about that. All right. Hit it once more. Did you see what happened? Right? That one little graphic gesture changed everything. Is it resonating? All right. One little piece. So if you decide to drink the Kool-Aid, and you really do decide that text is gone, and now the only thing I really have are pictures, now every brush stroke means something. Because what will happen if you write something that's gobbledygook, nobody's going to read it, and you're not going to be sort of happy about it. And if you draw a picture that's sort of thrown together, you're going to lose audio chip. Miles, there's 34 more out there, right? No, don't worry. All right. I want to be clear. There's more copies. You just hang tight there, and we'll get it at the end. All right. And you'll also get your bonus sign-up fee with some, we're doing time shares, I think, in some place. Anyway. All right. So let's not. So I will rule the world. And also, okay, so now we caption it up a bit. All right. We play with our captions, but that one little gesture changes everything. Okay. Let's talk. How we do it on time. So this is really, this is a poster child for really a nice piece of what I consider well-constructed documentation. Okay. We have the line, we don't have the outlining here, but you can see it's figured, it's figured and captured, and there's reinforcement. And the other thing is, let's go back to don't abuse, don't confuse. Here's what you don't ever want to do. People, you don't want to do that. You never want to do. People, you don't want the reader's mind to wander. Wandering is, goes into confusion. And so how many times have you read some, first of all, you've read something like take, you know, the figure, the figure, figure G will show you about how to plug in the amplifier. Well, where's G? Right. So I'm a big proponent of putting direction. Figure G below. Right. And also numbering and lettering, because if you don't, if you just do figure, where you caption without direction, the mind is going to start wandering. You're not thinking about your content. They're trying to navigate your document. And you don't want that. You want them to be very clear about what they're doing all the time. Don't confuse, don't abuse. All right. Hit it again. What do we got coming up next? Right. So here's just some more. This is a bad dog. On the left, you see it's like, here's this thing. It's sort of there. Granted, I gave you an outline, but I have no lead in. And just about everything I'm writing these days has a leading graphic. Everything I'm writing has a leading graphic. But you can see here, the purpose is to know what you're going to do. You got me. You got me next. All right. This is a bad dog. Okay. So we're trying to do a little thing here. And we got the numbering going. So now we know there's sequence to the diagram. There's sequence. That's good. One, two, three, four. I'm making Ajax call to a response to a server. And Ajax called back. And I got some stuff going on. But it's still pretty loose. Okay. Hit it. Boom. Okay. Now we're better. Okay. Now we're better. All right. Okay. You got me. There's 10% more effort there. But the rewards far out seed the expense. Far out seed the expense. All right. Next. All right. This one here, and this is new, but you can see we can get the pictures to start telling a story. And we get the pictures to start telling a story. So we know the mind, if we look at the pictures, we know one. Okay. And go to two. And then go to three. And now you got your story. Granted, do you feel the absence of captioning there? I do. I feel that the caption's not there. The caption is like, pulls it all together. And there's no caption. And now I'm lost. And now I'm lost. All right. Next. All right. This is, this is, this is where I'm at these days. This is where I'm at these days. This is about the Ready API test suite. But you can see it's one, two, three, four, five, six. There's something in there. You got me what this is about. I don't know. But I got that. The caption gives me some indication about the image. But now I have the text up front starting with figure 12 that shows me how to get through. All right. But again, the process is the same. Do the figure. Do the caption. Do the copy. Do the figure, caption, and copy. Okay. Let's go. All right. The pronouns. This is a big one. Good. Were you doing okay here? I mean, I'll sing if you need me to. All right. Yeah. Sure. What do you want? Yeah. Sure. Okay. Here's what I was taught. And now I tend to come from what I was taught. I was taught to do what's called value added captioning. You should never put in the caption what is stated in the copy. There's no value added to the caption. But if we go to the plan. This is hard. One of the hardest jobs in journalism is writing headlines. Usually difficult. Most people can't do it. And it goes back to captioning. So here we call it an obstacle. I need to write a caption that has meaning to the bigger picture, has meaning to the illustration, but it's not redundant to existing copy. And still keep the reader's attention. Am I answering your question? So we want to create enough thing that they'll get it if they go to the picture. Now the problem with this is it's a fairly detailed illustration. So you need, and it's sequential, and there's things going on in there. This is where video comes better. But videos create more crimes against humanity. And I'll go into that. All right. So we pick it up on top. So if indeed you find yourself saying, okay, this is how to plug the amplifier in and you've got a caption saying this is how to plug the amplifier in. It's going to confuse the reader out of a sense of what's going on. Why? Why are you doing this? And it's a hard skill. It really is. I'm not going to minimize it. Writing captions is hard. Okay? Good answer? Okay. Next. These, man, the pronouns. Oh, the pronouns. Oh, we hate the pronouns. If I never saw this again in my life, I would be a happy man. That's how much I hate these. I hate these in my sleep. All right? I hate them in my sleep. That's how much I hate these. All right? If this, that, these, then enough. All right, let's go. Hit it. Okay. That, this, that, these, though. Wow. Oh, I hate them. I hate them. Let's get it. You're doing a great job. All right. Okay. Next. Okay. Watch it. Okay. Hit it. All right. Trafalobors. Let me go back here so I'm not doing the evil thing of looking at the screen while I'm talking. I can have the viewer experience. This could be like UX. Okay. Trafalobors are the fundamental component of the Weeby Tata's framework. This screencast shows what they are about and how to use them. Okay. Right? That's really pretty cool. Okay. Hit it, Jules. Are we talking about they? Are we talking about the Trafalobors? Are we sure? Okay. Hit it. Are we talking about the Weeby Tata's? Well, first of all, you have no idea what a Trafalobor is. And you have no idea what a Weeby Tata is. And like you're, so you're confused the minute you walk through the door. I've already used language that has no meaning to you at all. I didn't say, by the way, Trafalobor parentheses is that thing you read about. It gave you some way to hold on. Remember that first example, four different things of value? Right? You have no way to hold on. I'm losing you. I'm losing you. All right, hit it. Good. One little word changes the whole show. One word changes the whole show. Is it clear? Yes. Trafalobor is a fundamental component of the Weeby Tata's framework. This screencast shows you what Trafalobors are about. Do not confuse. Do not abuse. Don't let the mind wander. Right? Your mind doesn't have other than, this is the most boring thing I've read, your mind has not a lot of opportunity to wander. Next. Okay. I'm doing a presentation in PowerPoint 2007 when, I'm sorry. I'm sorry. Okay. In slideshow mode, every time I move between slides, hitting the spacebar, I get an awful click sound. Does anybody know how to make that go away? Hit it. Did PowerPoint go away? Hit it. The slideshow mode go away. Hit it. The click sound. Which one do you want to go away? All of them. Make it all go away. Make it all go away. This is a bad dream. Hit it, Jules. There you go. Just make that sound go away. So when I do use a pronoun or that and this, I try not to use pronouns. And it gets tricky because now you've got redundancy issues and language issues and you have to write interesting stuff. If you use too many nouns repetitively, you hit that first thing and it gets a drag. It's a drag. But you don't want to do that. But make that sound go away. Okay. Next. Oh, that was pretty good. You did that. That was really good. There you go. Tell them three times. Keep going. All right. Now. Embrace revisions. All right. I'll share another story. I've got this story about what it took commercial interruption time. We saw the time, right? Hang tight. So I know I'm doing this presentation on Sunday. And I'm really psyched. Actually, I'm psyched. I thought we'd have six people in my dog. But we have, you know, the room is full and stuff. And I'm getting ready Friday. I'm getting ready Friday. I'm saying, this is great. And they want the slides. And I'm revising it and revising it and revising it and revising it. And my hard drive crashes. Bang. Right out. Done. So I'm never coming back. And I'm sitting here Friday night trying to get national. I'm talking to a guy. I'm writing an article for a thing. I need you to verify this illustration. Make sure it's accurate. And the machine's not coming up. You go home. You have to format the drive. Do I have time box or time share or any of that? Of course not. No. Luckily, you know, the important stuff's backed up. So you need everybody after you're through here. If you want to, you take my wife's email address and say, thank you for providing your laptop so I could show you this. Because my machine is completely fried. But that's not my tale of woe. This is my tale of woe. So I'm writing for developer.com. And I'm, you know, full of myself missing doing this. And I'm writing this thing about down and dirty async and await and C sharp. This really complex technical topic. And I'm doing all the right stuff. And I'm putting in the code examples. And I got the sample code. And everything's working. And I'm like a superstar. And I'm getting, look at it. I got five. And I got 101 likes. Which in tech journal land is like, I'm now God. Right? I'm now God. And 37 shares in my tweets. Probably 2 billion tweets. Meanwhile, you know, I'm still not seeing any increase in income. But I'm getting a lot of attention. But that's the increase in income. Right? So this is really, really cool. And then hit it. Boom. The code example was wrong. Luckily it didn't affect my like count at all. And luckily I didn't, nobody tweeted out about it. So here's the thing that I'm sharing with you. Even with the best of intentions, the best information you have at the time, the best expertise, your writing will become obsolete. If not in error. All right? And that's okay. Now, I don't, saying it's okay is a very broad statement. I mean, we don't want to produce information that's just blatantly wrong. We don't want to do that. But given the speed of change and the speed of having to acclimate this and get this all into our head. Anybody, any Ray Kurzweil fans here? Ray Kurzweil, the Singularity? Ray Kurzweil, yeah. Ray, let me give you, this is important. This is really important, particularly those of us in the tech game. Ray Kurzweil, the guy at Kurzweil, talking machines. He's now the head big guy at school. Okay? He wrote the Singularity is near. He has said he has eliminated type 2 diabetes from his body by doing vitamin regimens. He's a really, really, really bright guy. And he made a list of predictions over the next 50 years. And you'd be surprised. He's like 90% right on. And one of the things he's saying is that what's going to happen is that the amount of information that needs to be absorbed for a human being to participate in the modern world will exceed the physical capacity of that human being to acquire the knowledge. In other words, we won't be able to get it fast enough. It just won't happen. So his projection is first thing, in an education, you will no longer go study French. You will eat it. So you will have a little pill that you will eat that will alter your brain chemistry to allow you to speak and understand French. Okay? That's what Kurzweil is saying. The other thing Kurzweil is saying, which is pretty dramatic and we're seeing it, okay? We're seeing it is that he's saying that, no, the human body has outdated its usefulness. It is no longer adequate to absorb the information we need. So we're going to have to start becoming partially robotic. We're literally going to have to put, make part of ourselves digital mechanics, digital mechanical, digital biological. We're going to become partially robots. So what it means is that information streams, such as going back to French, you'll just change your biology to understand things, or you will have enhanced sensors. Now, there's a good argument to be made. Well, what's so different? I mean, before eyeglasses came along, a lot of people couldn't participate in the information structures. Now, we all wear eyeglasses or contact. Most people do. When you couldn't hear Beethoven, right? You had to listen. You didn't know what's on that. We have hearing aids. So that trend has always been there. It's not like dramatically new. But what we're going to start seeing now, and this is my prediction. My prediction is that within five years, how many people are actually talking to their cars every day now as a way of life? Okay. As the fleet starts to exhaust itself, fleets exhaust themselves. People will start talking to their cars more. That's just the way it is. You don't see driverless cars. The other thing that's going to happen is cell phone. Kurtzweil talks about miniaturization a lot. He's saying that the world is miniaturized and they have nano machines now. What's going to happen is your cell phone is going to go away and you're either going to have a coaxial implant or a coaxial optical implant. And we saw that they attempted it with Google Glass, right? And you might call it fantastic. It's not going to happen. What's that have to do with technical documentation? Well, it does because as information creators, we're going to have to consider what that next generation of information acquisition looks like, particularly at the educational level. So that's going to be revision. Revision cycle, getting it, understanding that next platform. If people said that hypertext would, think of what hypertext just did. I mean, no more, you know, you don't put your footnotes in that whole idea. Anyway, that's embrace revision. Next. All right. And I just pretty much what I talked about. What I talked about. All right, next. Okay. This is a big one that I need. This is my little diet tribe. How many people you're writing? How many people have work in companies that have at least 500 employees? How many people work in companies with 500 employees? I'm going to assume that with 60% engineering staff. How many people work 500 employees? 60% engineering staff. 50% engineering staff. All right. Okay. Maybe the room was larger. We'd see a shift in the numbers. All right. How many people you have a tech editor on staff? Good. You're my heroes. You get a parade. You get a parade. A tech, and not a tech writer. A tech editor. All right. Here's what, here's the deal. When I did my first book, I wrote my first book in 1996. All right. I wrote my first book. The technology is completely obsolete and worthless. But it did give me a royalty check to buy a car. Okay. The royalty check that came in last month, I got a candy bar. That's all right. But on that book, okay, I had an acquisition editor, a copy editor, a technical editor, a graphical editor, and me, five people dedicated to one book. All right. Now, my last article, which got popped, which is, we've had a minor inaccuracy, had pretty much me and some of the copy formatting. And we said, okay, we're going to now give technical editing to the, we're going to crowdsource technical editing. And one of the things we haven't been very good about in crowdsourcing technical editing is what's called, what I call, generous accommodation. It's really, Bob, you don't. I was lucky on that one. I was really lucky. I've seen stuff that's pretty vicious. So, one of the things that people start thinking about and say, okay, the first thing we need to do, the knee jerk reactions will hire a tech editor, a tech writer, and that will make everything better. No. Technical documentation needs to be as close to the subject matter expert as possible. But if you hire a tech editor, which is pretty, that will give you or your company the ability to produce quality documentation throughout the culture. Good tech editors are good teachers. They have a mastery of written and visual language. They see the bigger picture about how this all fits into a taxonomy. We can talk about taxonomies if you want me to. Yes? Yes, sure. First of all, a technical editor never creates content. Ever. They don't. They're given content. It's like any editor. At the editor level, they're given content and they go through and they say, okay, this doesn't make sense. This doesn't make sense. This is not needed. Cut. You're gone. They need this chapter. They do the fundamental mechanics of documentation management. That's one thing. The other thing they'll do is like they'll see, like the pronouns are bad. That's copy editing slash technical editing. The last thing they do when I started as a technical editor, by the way, was you go in and you actually do everything. So if you do everything that's supposed to be done to make sure it's accurate. So I would get a, let's say I was doing a programming book. I'd get a programming sample. I'd go through, set up, do the programming, make sure it worked. And everything that was talked about was indeed accurate. And that's what technical editors do. What? The technical editor is contaminated. It's like anybody else. You don't, any content creator is by nature. You don't see it. All right. You just, you don't, you don't see it. That's why one of the fundamental rules of public publishing is you always have a second set of eyeballs. No matter what. I've done it. VV. You ever see two Vs? VV or people leaving this? You just don't see it. You're contaminated. So, you know, the fantastic story is, is that the, when, when, when, when Columbus showed up on the shores of Santa, Santa Domingo, the, the Indians couldn't see him. They didn't have a concept for Columbus. They just didn't see it. All right. Jared Diamond talks about this. And, but what they did see is that the alteration in the way, they saw the alteration in the waves. They couldn't see the boats on the horizon. They, there's no boat under, they couldn't do it. But they saw that the waves were coming in differently. They were contaminated. They were part of their culture. So, the writer is completely contaminated, even at the copy level, at the technology level. How many people have you, have you ever written, I do this all the time. You write something or you make a picture and you bring it to a subject matter expert or somebody else in the know and says, do you understand what I'm talking about? And if they say no, that's all right. That's good. That's good. Now the trick is, and most people can't do this, is where am I confusing you? That's the next step, is me saying, how is my writing confusing you? Tell me, where, what aren't you getting? Most people can't do that. Most, I wish they did, but most. Did I answer your question? Okay. And I'm happy to go into it afterwards. Do you have a follow up? Looks like you do. Okay. I'm happy to do it. All right. So, but bring that, if you can man, we can do a t-shirt. Bring back, bring back to that line. Okay. Next. Okay. Video. Let's talk about video. All right. Michael Jackson, right? I'm Michael Jackson now. Okay. I'll do my moon walk. All right. Video. Video. We're all, video to the masses. YouTube. See, YouTube, everybody's a star, right? All right. So, what's the deal? Here's the deal. When I was back in college, the film students, when I was back in the seminary, when I was back in college, the film students, you had to be, being a film student in 1973 was, you had to be prepared to pay a price. And that price was $1,000 a minute. That's what it cost to make film in 1973. $1,000 a minute. So, as a result, everybody really thought about their minutes. Everybody really thought about their page count when that page count cost money, right? Everybody thought about their photo resolution, but they still do, even in the digital age, like digital compression when, when bandwidth costs money. People thought about it. And there was a wonderful efficiency and a wonderful creativity that was created around that, lack of resource, right? It's a really one, when you run out of stuff, you become very creative very quickly. But we've lost that, okay? The other thing is, is that I was taught, is that, and this is, one word is one second. So, if you plan to do a 60-second commercial, and this is interesting, if you want to go back, look at commercial word counts. Really, these guys got it down, because they understand the scope of human attention. But if you're going to do a video, and you have 5,000 words in your copy, well that's 5,000 seconds, which is a 10-minute video, and a 10-minute technical video is a lot. You better be prepared to pay a big price. But it's free. It's free. So we don't care. We don't care. Because all I got to do is get my screen capture stuff and talk, and I'll get a lot of attention and all that. And so we're losing this elegance of really good didactics, really good educational quality material. And we're losing it. And I'm going to demonstrate what I mean by that in a minute. And then we're also losing production quality. So if you want, the real, the big players, Microsoft gets it. When you've got tens of millions of dollars, you get it. But those numbers are shrinking. I mean, everybody's saying, if this doesn't produce me revenue immediately, I'm done. I'm done. All right, let's go next. This is my closing. I'm going to do, let's do Good Dog, Bad Dog. Let's hit Bad Dog a minute. I want you to look. We'll do this one again. But I'm going to show you Good Dog, Bad Dog, and then I'm going to ask Jules to go back up again, and we'll look at it again. And I'm going to tell you when to cut, because hit Good, hit Bad Dog. No, no, no, hit, literally go back. Can you see the Bad Dog circle? Hit the Bad Dog. Yeah, yeah, watch. Just watch. Okay, stop. All right, let that go. Okay, now go back to the PowerPoint. I think you can tab through. No, just hit tab window. Yeah, up top, here. This one's a little bit beyond. This is technical. Thank you. You're doing a great job. Okay. Oh, you're listening to the video. Okay, now watch Good Dog. Did you see that? Let's do it again, because this is critical information. Okay, now we're going to do Bad Dog. Okay, one, two, three, four. Five, six, seven, eight, nine, ten, eleven, twelve. Twelve seconds, right? What was the, what value did you get from that twelve seconds? Cool, right? Absolutely, there's absolutely no educational value. No reader value from that twelve seconds. Now, twelve seconds, right? That twelve seconds going back, that's a fifth of a minute in old film school times, a $250 expense. Right? What did it get you? So, the point is, I mean, let the music do the talking, right? We've become indulgent in, it's become indulgence. And when you want to do video, and I'm a big video fan, I like video, I like video for teaching, I like video for documentation. But be very aware that you just, you just, you can't, you know. Yeah, excuse me while I take twelve minutes of your life, or twelve seconds of your life and give you nothing in return. All right, excuse me while I do that. All right, was that useful? That's the first time I've done this in this presentation. I hope there's use. I mean, that one just hit me right out. Boom, right? And that goes back into, I'll do, if people want to take me outside and talk about video production, I'd do didactics around it, how to do documentation around video production, and stuff like that. All right, next. All right, so let's wrap it up. Okay, several. Number one, if you don't want to read it, don't write it. Number two, don't confuse and don't abuse. Number three, before you start, be clear about what you want the reader to do when you end. It's a contract. You're making an agreement. Keep to your agreement, all right? And you can do that in your thing. At the end of this document, you will be able to do ABCDEFG. And if you're writing and you find out you're not keeping your agreement, nothing says you can't go up to the top and change the agreement, but make an agreement. Next. Okay, you're right to an outline. Always, always, always. Next. Okay, clarity equals illustrations and words. You can't have one without the other. Two, go. Watch the pronouns. They suck, right? Seven. Okay, embrace revision. Okay, any questions? We do have a little time. Of course, that's it. That's the show. Go to the world at WhichWeLive.com. Sign up, get on the list. I'll send you a cartoon every Monday to make your day brighter. Question. No, I didn't say that. No, go ahead. What was your question? Yeah, the point is, if you have a root and you never have an orphan, all right, let's scroll back up. You mind, well, I want to take a minute. If you've got to go, you've got to go. I get this. It's a good question. We'll go up, up, up, up, up, up, up. About orphan outlines. Go down. Go down. Yeah, here. All right, go back up one. Okay, let's say this is about orphans. All right, do you see here that we have three levels of outline? One, assume knowledge to dots dash dot. And do you see here that we have the orphan and they know about the file system of the web app and then Webim should have meaning? So that's an orphan. We agree there. So the question is, what's the root? Both of those know about the file system of a web app is useful topical information. Agreed? But is it really a root? It's just something else. So my position is know how to write web apps. And part of knowing how to write web apps is that you need to know about the file system and you need to know about the relationship of Webim to the web app. So the remedy was really to push your root into a peer. Does that make sense? So when you find orphans, most likely either there's not a lot of logical choice here. Either you need a peer, you need a peer. So either I have to create a peer or I become the root. So here's my orphan, so I need to do one of those and create another peer for myself or I need to become a root. Any other questions? Hey, you've been a wonderful, oh wait, okay, oh, sorry, I wanted to do, well, it depends on your delivery mechanism. Okay, if you're doing, you're doing inline. Video is a strange beast. Video is a strange beast because it can be innately textual. All right, if you have to put, the fast answer is I don't have a fast answer. Video production is much more elaborate. It has to be much more well thought out, understanding your didactic points. I can talk, that's another talk. I mean, I've done video. You have to, the script, how many people, it's the script. It really is the full Hollywood version shooting script. You really need to understand what your language you're supporting, what your voiceover supporting, what your visual is supporting, and then overall what your approach, even the zoom in, zoom out, all that stuff really counts. That's why video is, bad video is cheap, good video is expensive. No, you should learn how to do good video. Well, we can talk about it offline if you want. It's not that, it's hard, but you've got to start someplace. And what most people do is they do too much. So you want to start something like really simple. Actually what's really, okay, no video should really be more than five minutes. If you want to stick around during the break, I'll talk about it. I don't want to hold people up to half the places to go, but I'm happy to do that. Any other questions? Sure, my email address. It's been a stepchild, except the only place it's not a stepchild is when, let me do it. Okay, here's the fast one. Here is the continuum of software development. The continuum of software development is over here you've got your porn, right? Put the picture up and get the money, right? And then over here you've got your department of defense. We're going to blow stuff up and kill people, right? And medical, right? And so the interesting thing is over here there's not a lot of documentation requirements. You just don't, you can make a boatload of money and never document a thing, right? And nobody's going to die and if they do, it's probably nothing you did directly. Unless you don't remember how Nelson Rockefeller went. Anyway, you know how Nelson Rockefeller went? He died in bed with his secretary. Anyway, but nobody's going to go, okay? And over here, DOD, DOD Medical, people really do die. It's usually regulated and reproduction. Then you've got the ISO, ISO 9000 Levels 1, 2, 3, 4, 5, all that stuff sits in here. Over here the documentation is really good. It is. It's dry as all hell, but it's good because it's got to be. Most companies, in my experience, you've got your porn, you've got your DOD. I'm going to tell you what. Here's, we're going to have a real-life example before you go. I'm going to start here. And as your company comes on the spectrum, raise your hand, okay? Porn, DOD, okay? Did I make the exercise clear? So as I come into the spectrum of your company, put your hand up. Okay, here we go. There you are. Does it have to be that way? No. Good news is, there's a lot of autogen documentation. And then we've seen Swagger, Swagger Hub, Swagger I.O. The Swagger people are doing an excellent job of creating autogen. You want to get it on the SME level, such that our expert is quickly responsible. So you can use Swagger annotation, you can use Java Doc. At the code level, it's really good. At the systems level, it's a little more difficult. But still, on your Jenkins plugins, you can do stuff like that. But it's nobody else. I'll give you my email address. I'll come to your company mail instead of straight. We'll talk about porn and DOD. It'll be a great time for all. Any other questions? Okay, people I want to know about, particularly as a video, we can meet up out front so we don't tire of the room. Thank you for coming. I know it's Sunday. Don't forget the world in which we live. I have three cartoons to give out. If you want them, come see me. Thank you for coming. Thank you. We couldn't have done it without you. Thank you.