 So I'm going to be talking about documentation because I hate to tell you this, everyone dies. You could get hit by a bus. Then where your projects are going to be. I know you don't care, but other people don't care. So two things first. It is okay if you fall asleep. It's the end of the day. It's hot. You've been busy listening to lots of things. I know when I'm at a conference, I'm just behind a stand all day. And if I sit down for like five minutes, I doze off. So I'm not going to be offended. I totally get it. Secondly, it's okay if you can't quite understand me. I grew up in Los Angeles. I then moved to New Orleans. Then I moved to Nottingham. And now I'm here at Belfast. I know my English is not your English. It's mine. Come get me afterwards. We'll try to make it make sense. So to start out, I have two stories. These are things that happen to me. Like we said, I did my first website in 1995. I've been working in the business since about 2000. A lot of terrible companies. The first one was I was tempting for a job, or a CSS design job. The designer had broken his collarbone in an accident and could not type. And they desperately needed to get this website done urgently. They needed somebody to come in and be able to do it. This was in 2004. So my CSS knowledge was not so hot. But I wasn't given something like that. I was given beautifully laid out code. He had comments in explaining what each single bit did. He had everything organized, filed perfectly. And I learned more about CSS in those two weeks than I had the years before. Because he just documented everything so damn well. I don't know who that guy is. I love him. My second one. It was a developer. This was when I was working for a tiny e-commerce shop. And I was in charge of all the front-end stuff. And we outsourced all the back-end, the development, the hosting. And we had a problem with our website. It was down. We were losing tens of pounds. Tens of pounds, my God. And it was completely broken. And we kept them trying to call the owner. And we kept them trying to get the developer involved. We kept them going, what's happening? What's happening? What's happening? The site's down. And it turned out that the one guy in the company who knew everything, who was responsible for running the site, who had all the skills, was bit by a dog. And bit by a dog on his hands to the point of being these digits, and he could not type for weeks. To get our site back up, he had to go in, stand there, and tell them how to fix the site while basically going like this. Bad documentation meant that my site didn't go back up. And I got yelled at for the whole tens of pounds that we lost. So documentation is incredibly important. It's incredibly important to you. You are also important to you. This is why you should document stuff. It gives you a reminder of what you've done. How do I do this? What magic was this? You're never going to have to go, was I smoking something? That's fine. What have I just done? And it also tells you what things connect to. That way you don't look at a piece of code you did five years ago and go, I have no memory of what I've just done here. Don't get magic. What if I change something? I have broken everything. Oh, God. So it gives you a reminder of exactly what you've done. It gives you a process. That's why you know that when you make A, it will affect B, and then that will produce C, because you've written all down exactly what it does. And that means that if it does go wrong, you could go, I wrote down where I went wrong the last time. I'm not going to do that again. Next time it's going to go like this, because you remember how it all works. And above all else, it gives you proof. You don't know how many people I know who have to, are suddenly told, write up what you've done for the week, and have absolutely no memory. Just go, I've made something. But look, it shows you. Look at all the work you've done. Look how much you've grown over the years. I mean, if we look back at my website in 1995, damn. And basically, it means that if you go to your job, your performance review, or you go to a new job, you could go, look at everything I've done. Give me all the money. They might not give it to you, but you've got evidence. And it's very important to everybody you work with. I'm not just talking about your boss. I'm talking about your coworkers. I'm talking about your employees. I'm talking about people you don't even know exist yet, but will be touching your code. They're also important to them. They have their own lives. They need you to be better, to document. It gives them the support that they need. What works where? How does everything connect? And above all else, they don't have to bother you anymore. I know me personally, I hate bothering people. I know you don't believe that, but it's true. I hate to ask people, what have you done here? How is this broken? How can I fix it? Because I don't want them to think that I can't fix it for them. I don't want to have to ask them how things have happened. I just want to be able to do it. And with good documentation, I can just do it. I don't have to bother people. Especially if you're on holiday. Finally, you finally have two weeks in a beautiful place. Do you really want to get that phone call of somebody who is apparently just learning how to change one CSS file? You don't. Documentation. And it gives them the understanding. You want everybody to be on the same level. You want people to understand exactly what you're doing. And then, that way, you can all work together. You get how you... They get how you're working. They understand. They can then build upon that to make even more neat things. And everybody's on the same level or improving together. Management, it gives them evidence. They know what you're doing. They know how hard you have worked. My God, you have worked so hard. Why don't you show it to them? And then, they throw all the money at you. And if they don't, then another company will throw all the money at you. You know, a lot of people go, oh, God, no, this is too hard. I can't cope. I don't ever want to do documentation. No, it actually is really easy. You don't need to be writing epic manuals. No, I've done that. You know what? Nobody reads them. It's horrible. You document why you work. You don't have to comment out every single line. You don't have to provide a giant manual. Just quit, little, explain what's going on. This particular bit of code creates a box that's to the left, and it's blue. And if you put it in here, it turns green. That's it. And if you want to, you can document after you're done. You can produce the bigger picture, overarching, giant detail manual. It can also, that can really help you, because then you can look back at what you've done, taking those little bits of comments, and go, oh, if I had done this bit first, I wouldn't have had to spend days on that stupid part. Because you would understand how it's been working. And then also briefing someone else. You know the rubber duck theory, where you tell your bugs rubber ducks in order to understand what you've done, because it's the second person you're talking to. Talk to a real person. You tell them what's going on. You figure out together how things work, and maybe you'll pick up new things. Maybe they'll pick up new things. Maybe you'll guys will come together and then create the next multi-million-pound super project, because you just talked about that tiny bit of code. It could happen. So, why is documentation awesome again? You know what it is. It is. It shows you what you've been doing. It shows your coworkers. It shows your boss. What if open source projects help? It shows the entire world. But you want. You want people to know that you are making fantastic stuff. And, why not tell them? Or even better, why not just be left alone by not having to have people question you about things, because it's all right there. You can either be showing off, or you can be left alone. You can do both with documentation. So, if you have any questions, you can. I knew it was under 10 minutes. Hot damn! If you don't, I'm on Twitter. I don't recommend following me, because it's literally pictures of the cat that hangs out while you go up. Unless that's what you're into. Go team. Or you can find me tomorrow. I'll be at my stand. You can talk to me anytime. But if you have questions, now is the chance. Thank you. The next time I come to that decision tree is to spend the next two-hour documenting that. I'm going to have to go back and watch the video of this doc, because that was fantastic. I was so motivated to document something after that. It's the phone call Thursday afternoon while you're on the beach. Or while you're making Easter dinner. Because that has happened to me. And I said, I have documented it. You don't read your damn emails. See, that is the problem. You can document it. But at least you've done it. And you could go, so you've read my emails, yes? Bye. Slime. Okay, here's a bold first question. What exactly is documentation? It could be anything that explains what you've done. Because I would have thought it could be everything from comments on a line of code to a git commit message to the full life story with a thousand more articles about why you've done that one thing. It can. I always like, because basically most of the time I come into a project it's after somebody's left and there's nothing. And anything that remotely resembles documentation is therefore a God's end. So, yeah, it's all dependent upon what you need to do during the process that you're making something. A lot of people go, I don't have time to think about documenting it. You have five seconds to write a comment. It'll help you in the end anyway. It'll help you anyway. Or you might have, you might get lucky and you might have a proper sprint system where you have the meeting afterwards where you go over where everything is done and those minutes, if you want to take minutes, the minute, you can take minutes and that can be your documentation on it. So, basically, there's a lot of opportunities that you just need to go, you know, since we're talking about this, let's just write it down. I can empathize as well with when I'm writing the documentation before I flesh it out. So, proper English, I write just bullet point notes with very sure hand and that's enough for some people. But in terms of writing documentation, are there any things you would recommend not to do, things to avoid, pitfalls, problems? Giant paragraphs. You know how you start out with a bullet point and that's fine? Oftentimes, that's all you need. You might want to maybe expand it out to a sentence. I actually just wrote a guide for our resellers on data protection. Keeping it very vague, because I know I'm not a lawyer. And I started out, I just basically bullet pointed everything I knew I needed to put in there and then most of the time, it was just turning it into a proper sentence and it was done. If you know that you want to talk people through a particular process, order this. One, two, three, four. Click, click, click, go. Immensely save so much people, so much time. They go, wait, where do I go? Don't forget file names. Just say, this is the book that tells you everything. What about publishing documentation? Where do you put it? Usually most of my documentation is completely internal, so it just sits on our internal compliance section. With very clearly said, this is this thing. But other times, if it's say a manual for customers, it goes up in all the appropriate channels that the people might see it. If it's a project that we've worked on and we're really proud of, we'll put a blog list about it. Going, hey, check this out. This is all the stuff it does. Here's where we might have had some snacks, but we totally got it sorted because we're cool and this is how we're cool. And do you then treat that like any other content artifact where you then come back to it six months later ooh, is that up today? Or is that gone stale? Are you extending like a content team around documentation or is this... The content team with me. Sometimes I do go back to it. Sometimes I go, well, that's how it was at that time and if I were to go back and fix it that I'm going to put something new up because things have changed, which is the big thing to say. Well, back then, that's how it worked. We've had to make some changes. Here are all the changes. Now that works. Anybody else questions? I was asked there with that. So you said all of your stuff is internal documentation. I presume that processes the way your team works. Yes. So therefore I presume that would change over time. How does that get reviewed? It gets revisited when it changes. So my best example is for some reason, WordPress and our blog and our servers don't like to talk to each other particularly much sometimes. So you have to change your host files and your staging servers. You can upload the images right so that then you can sync them in. Eventually we're going to fix this and then I'm going to go back and I'm going to go again. So all of that, that's gone. You don't have to deal with that now. We can make it easy. Right now it's a disaster. So a lot of it is going, well, this is currently a disaster but here are our fixes around it. Then when we get it fixed, here is how it actually works. We're doing this right. Because I hear so many people saying our documentation is terrible but I'd like some of this done. You know what, we're pretty down good at this. I mean it's not quite full-time but I really like Mailchimp's style guide. I'm used to Mailchimp. Because they have it all out there and they say this is exactly what it is and it doesn't get as bogged down as style guides get. The logo must be 50 pixels that way. A lot of good, some newspapers have their tone of voice articles as well. Those are all fantastic. I mean the Metro doesn't have it out for me. And then just basically look at non-software companies because they might have something up there and it tends to be, especially the bigger companies, they tend to have an entire company involved around it. I like to think some of my documentation is good. I'm sure everybody can tear it apart so it's usually just me going, what have I done? Okay, that was absolutely great. I can't think of a way to finish today so thank you very much.