 Thank you very much. Thank you very much Belgrade, and it's good to see you all this afternoon. Thank you for sticking around for the final block of WordCamp, I'm sorry. Who in the room would have at some points in our lives said that we are a programmer? I presume more than a few of us. I think that we are diluting ourselves and also selling ourselves short, because I actually believe, and the title of this talk may not necessarily make this clear, but I believe that programming is not the hard part of what we do day to day. The hard part of what we do day to day, I believe, to be all of these other things that we actually spend more time on on most days than we do coding. The communication and the process that surrounds the programming, that surrounds those narrow windows of time where we are actually writing code into a text editor. And these things are difficult because we don't have linting or modern frameworks to handle all of them. There's definitely processes that we use to make things better, like Agile and Scrum, but we fall down on some of these other types of meta-task that we end up running into over and over again on every project, whether we are a freelancer or working on the largest scale WordPress sites in the world. Fortunately, there is one thing that I think helps with many of these, and that is documentation. So today, we're going to be talking a little bit more about what we can do with this to make our other processes more efficient. A couple weeks ago, I was talking with a developer and asked what they did for docs, and they said, oh, we just do readme files. And this struck me because, first of all, I don't think you should ever sound embarrassed when you're talking about your documentation. If you have it, you're far ahead of far too many of us. And also, markdown files and readme's, I think, are underestimated. And there are things that we can do with a simple markdown file that can be really beneficial to our overall process. The reason that this is true is because we document and we're used to documenting our interfaces and APIs, and we can also document the processes that surround our daily workflows. For example, with pull requests. If I'm asked to review a pull request like this, there's not actually a lot of information that I've been given about it. The best I can probably do is to skim it for obvious logical errors, but I can't say whether I think it's a good solution to the problem right away, because I haven't been told what problem this pull request is trying to solve. If you think about the name pull request or PR, if we're requesting our code be added to a project, that's communication. And we are not communicating unless we provide additional words to surround our code that make it easier for our teammates to step in and perform this review. Taking an extra five minutes to give our teammates some background on the bug that we're trying to solve, maybe some screenshots. I love screen capture gifts as a particularly useful tool when you're working on UI. This can make the person who picks up the review of this much more able to tackle the question of whether the solution that you have picked is not simply correct from a code standpoint but correct logically. But we're all very busy. What can we do to actually make ourselves take the time to sit down and write this additional description? If we are moving from one bug to the next, we want to jump to the next piece of code because the coding is what we find to be fun. Well, we can document what we expect. GitHub supports creating templates using the markdown syntax that will appear in the editor of the pull request or issue text area when we go to open our ticket. We can use comments in these markdown template files to instruct our teammates and ourselves in what we consider to be proper documentation for this type of pull request. Without templates, we get vague issues. Again, we're in a hurry. We want to keep going. But more detail is always better, especially with open source. If you're working on a project like Gutenberg and you just put up an issue saying it doesn't work, that's of no use to the development team, and it actually does a disservice to yourself because then your bug will never get prioritized and triaged. Whereas if you follow the issue template that the Gutenberg developers have put forward, you can say, oh, I should include what I expect it to happen. The steps to reproduce may be a screenshot of the visual issue that I have encountered. This additional information makes it much easier for the team managing that project to go forward and take it and make sure that this gets solved and that it's merged back into the core Gutenberg plugin. If used in this way, issue templates can define a standard of communication for our entire team. They remind us to respect our colleague's time as we would our own. Standards like that should never be ambiguous. So if there is something that you find is going to make your team better able to communicate, that should be written down. It doesn't have to be in a template file like this, but the benefit of putting it in a Markdown template is that it's right there where you need it to be. I'm a big believer in co-locating documentation, putting it as close to the code or the task that it relates to as possible. And if we use issue templates, then that documentation appears right in the text editor where we might need it. This is why I'm a big fan of Markdown files like the Read Me as well. It's a relatively humble file, but it's the first thing that any of your users or contributors to your project will see, because we're used to, particularly with tools like GitHub and Bitbucket, that when we see our code, right below the code, we have the Read Me. Open source Read Me's, I think the ones that are really successful, tends to be very complete. They might have not just the information about what the Read Me is for, or what the library of the Read Me documents is for, but also background on why it exists, how to install it, getting started instructions. In Redux's case, they even have links to video tutorials and blog posts and a whole host of sample applications. As well as a quick section about when Redux would not be the appropriate solution for an application. And this is something else that we probably don't think to document often enough. When is the tool that we are building not the right solution for the job? So that's a good Read Me for an open source project, but the projects that we work on for client work might actually look quite different. The projects that we work on for something like Gutenberg will be different still. What information belongs in a Read Me depends on the context. Our Read Me's for human-made projects, for example, focus on things like team hierarchies and responsibilities, on-boarding steps, the questions that we will be asking if another person from our company joins the project, or when we hand it off to a client's development team. Gutenberg, on the other hand, actually almost completely excludes any of the technical information that we might see in a Read Me for a library like Redux in favor of more of a philosophical background about the editing focus, the stages of the project, how to get involved. This is, for Gutenberg, the most important thing. And so by moving all of those other technical steps out into another file, it's able to answer the key questions that people might have when coming to this project on GitHub. And we have good places to put all of these other technical instructions. Contributing.md, for example, is a great place for knowing how to set things up, how to get the unit tests running, and also information about behavioral expectations on the team and overall team project management process. Contributing.md, and actually there's the ability to add a code of conduct file as well, are also something that GitHub has done a good job of highlighting, because if I go to contribute to a repository that I haven't submitted any code to previously, those things get called out, so I can think, oh, there's actually instructions for what I should be doing here. There's instructions about the behavior that I'm expected to conform to to be a part of this community. That's great information, and again, by having it right there in your repository as text files, our tools like GitHub are able to put it right where it's needed when you need it. We can, of course, put entire handbooks or user documentation in our repositories as well, but something that I've been seeing more and more recently is actually taking small pieces of text and putting them all over your repository where they need to go. Projects like Gutenberg have readme files throughout in many different folders, and each readme will be explaining some of the information about what the component or module that its folder contains actually does in its purpose and its use. These readme files get displayed as we browse the project, and by being right there next to the code, they make it much easier for us to keep this documentation up-to-date in a living way as we modify the code, just as you would not think to submit a change to code without updating the corresponding unit tests because it would fail continuous integration if the readme file is right there. Maybe we can have a step to update the documentation whenever we update behavior as well. Or we could go one step further. For a number of years now, there's actually been several people who have been proposing writing the documentation first, putting an empty readme in an empty directory before we start coding at all. And this is really interesting to me because now, when you start imagining a new feature, you're thinking more about its use. You're not thinking about the technical specifics. You're thinking about the challenges that you're trying to solve. Explaining what you intend to build in your documentation as you would to a user, you'll spot issues before you even begin to code. You're giving yourself a chance to think through the design without getting bogged down and having to update all of the related code every time you change your mind. Once you finally do sit down and begin to implement, then this file will live on to become the readme for the new functionality. I'm not here today to tell you you have to do things this way, and this certainly isn't only relevant with markdown files or on GitHub, but the closer that we can bring documentation into our day-to-day development process, I think the more productive we are, and I think there is a lot to be gained whether you're using readme files or Wiki for your information or like the WordPress handbooks, something like a CMS-like WordPress, having that documentation be something that we continually refer to and continually reevaluate is beneficial to us all. And even if you don't have any other text files, I think every project should have a readme because this is the file that we will see first when we open the code, and it can serve as a portal to Confluence or wherever else we end up storing that documentation. It should exist. It should be a visible point of entry, and we should make sure that we keep it updated because documentation doesn't have to come first, but if it's an afterthought, then I think we're failing ourselves and our teams. Everything that I've said here today has been said before, and the idea that writing docs can make you a better programmer is in no way new, but we keep having to relearn it. We keep rediscovering how much more effective our teams are if we actually agree on and document the ways that we intend to communicate with each other. So I hope that you'll take the time to give documentation the time that it deserves and that you'll share your successes with others so that they may do the same. Thank you very much, Ward Camp Europe. Thank you. Questions? We have one here. It is very nice to see you. So could you go back for a minute to the part where you showed us which elements a good written would have? So I saw that you have to put in what it should put in, what the code is for, what the project philosophy is, where not to use it, and there were some other... There were, so in the version of my slides that I have online, there's actually a bulleted list. I think that's faster than going through the animation again. Keynote's kind of slow at that. But also I would say that it does depend on the type of project that you're working on. So if I was working on a plug-in for the WordPress community, I would probably be focusing on installation instructions and where to find documentation and support information and then move the technical information about how to maintain it either farther down or into a contributing file because that's more relevant to the company that's maintaining that plug-in or the community that's maintaining that plug-in. Whereas for something like Redux, technical specifics of how to use it comes front and center and the video resources that they provide help people who might have different modes of learning because some people like to learn by text, some by video, some just by getting down and coding. Those sorts of resources are mostly useful, so for something that's more on the technical end of the spectrum. Thanks. Thank you. Thank you. More questions? Yes, one there. Thank you. Thank you for this great talk. You quickly mentioned that you like screen recordings in GIF form. Do you have a recommendation for Sleek Workflow to create them quickly and effortlessly? There's some great tools. I believe one called for Mac OS called CAPKAP that has a nice user interface. I use Linux, so I can't use that. Lyscap, L-I-C-E-C-A-P is one that I believe exists for both Windows and Mac OS. Ubuntu has some native screen recording functionality built in, so I usually use that and then convert that to a GIF when I upload it. It's command shift option R, I think. I don't know actually what it's called. It's just part of the operating system. There's a lot of good video capture tools out there. Many of them let you set a window, and those are the most useful because you don't have to have your whole browser test bar. Can you post that on Twitter? Yeah, sure. I'll try to do some research and post it to the hashtag later on. Take a picture of all of Catam's links so you can follow him and follow up with more questions that I hope will come up after you review the slides. Please pull me aside and talk to me if you see me and want to talk about documentation. I love this stuff. There's a really great community out there called writethedocs.org that has a lot of great best practices for documentation, so check them out as well. They have documentation online and also a series of conferences worldwide. That would have been my question. Where do we get more resources to get better at this? Writethedocs is one. And also just remembering what projects you've used that you think actually have really great documentation. Again, I used Gutenberg examples, not just because it's a major topic of focus for us in the WordPress community, but because I think they're doing so many things right. So figuring out which projects you find to be easy to use, you can look at them and you can look at what they're doing and take that and use those same practices yourself. Yes. We have time for one more super quick question. Or you can look for Catam outside. Are you going to be here this afternoon? Absolutely. I'll be around all day. All right. So thank you very much for being with us. Thank you. And thank you.