00:00:07.759
Hello, audience. Check out these shades! Pretty rad, right? Does anybody know why I'm on stage wearing sunglasses inside like an idiot? Let me give you a hint: you don't know because I have not told you. Communication is important, and without clear communication, without me explicitly telling you why I'm doing this, you're forced to ask questions and make assumptions. Like, why is he up there? Why is he wearing glasses? Is he kind of a jerk? Is he hungover? Is he crying? What's going on here?
00:00:18.560
Mostly, I thought it would make you look cool. But this is for a point: communication is important. Without proper communication, you have to go on wild sprees and make up things for yourself. It's really inefficient, and this goes double for code. Code documentation is your communication within code, and it is important—more or less—and that's what I want to talk about today.
00:00:40.320
This stuff is really important; this is what we do at GitHub. Let me tell you a dirty secret: humans are not Ruby interpreters. People like to say, "Yeah, I'm a developer. My code is awesome, no matter what I write! I can easily see everything I need to know." That's not true. Yes, you can sort of stumble through, but if you've spent 5, 10, or even 15 years writing Ruby, if you've been writing code since 1970, I guarantee you're going to be better at reading English or your native language.
00:01:10.880
And that’s why I think documentation is really important. That's what I want to talk about today: how documentation can help you be better as a developer. So I'm Zach Holman, and I'm @holman on Twitter and @holman on GitHub. I am drinking a fine Boulder beer, so if you throw your tomatoes, please don’t ruin the beer. I do work for GitHub, which I guess people consider a code host or something like SourceForge... sort of.
00:01:51.680
I know you guys love Twitter, and I know you're going to have the Twitter back channel during my talk. I know you're going to talk about me behind my back, so I'd like to consolidate all of that into one hashtag for this talk. This is the hashtag: it's 139 characters long, so make sure your punctuation is chosen quite well. Now, let's get into it. If you're like me, you're going to ask the wrong question. Why should we do this? If you're thinking about documentation, what's the big deal about all this?
00:02:32.319
I have to confess: I hate documentation. Maybe I'm not the right person for this talk, but I'll wing it. I don't like documentation. This is me, circa a year ago. The main reason I didn't like documentation was that it felt like a lot of process. It felt really heavy, and I hate processes. I hate meetings; I hate anything that gets in the way of me doing actual work. It really feels like any sort of upfront planning is just useless. So I'm really skeptical of this sort of stuff, but most importantly, I don't like to help people.
00:03:19.440
This is kind of an important thing: yes, if what I do ultimately helps people, that’s great. But when you come down to it, I don't want to do something for my manager or for users. First and foremost, I want to help myself. If that stuff happens down the line, that's great, but I'm not going to do something unless I see direct benefit to myself. I think that's important if you're looking at any sort of development mentality. It should be: "if it’s going to help me, then I'm going to do it." Documentation should be selfish; I think that’s really important.
00:04:05.760
I don't think it's a bad thing to say. As long as you get into a system that you are comfortable with, I think that’s a good thing. These are the three things that I found documentation helps me the most, and these are what I'm going to cover today. First and foremost, this stuff has helped my Ruby coding a lot. I know a lot of people who sit down at the keyboard and start typing code, and just like beauty flows from their fingers. When I get to the keyboard, sewage runs through my fingers into whatever I'm using.
00:04:43.200
I can write beautiful code. I really can, but it’s really difficult for me. I have to think about how this is going to be designed—how am I actually going to tackle this? Documentation, in a variety of ways, has helped me write better code, and I will talk about that a little bit later. Secondly, tests: when you have better Ruby code, you write better tests. The act of writing documentation has also helped me figure out how I want to test things, what edge cases I want to cover, the whole gamut of that stuff. But first, I want to talk about projects.
00:05:25.920
I love projects. I write lots of little Sinatra apps, little stupid gems, and I write Ruby libraries—a whole slew of things. I really like the idea that you can do really small projects, ship them, and have a good time. So it was important for me to find a mentality that would work and help me produce top-notch projects as fast as possible; that’s an ultimate win for me. I want to talk a little bit about README-driven development. This was mentioned a little bit yesterday, and I’ll dive into it a little more today.
00:06:05.440
README-driven development was invented by this guy, Tom Preston-Warner. He’s a co-founder of GitHub, which is why I'm talking about it. We get docked pay unless we have three mentions... just kidding. I'm discussing this because it’s really cool and has changed how I work and how we operate at GitHub. So, step one is you write your README; step two: there’s no step two. I really apologize; that was the worst joke ever. Everybody uses it, but that’s really all there is.
00:07:04.400
You sit down, write the README. You write your installation steps; you write how the public API is going to be handled or whatever to-do items need addressing. You write that all first before you write a lick of code or tests or anything else. This is the reason developers have this tendency: if you have a cool project idea, the first thing you think of is the most interesting part. If you're going to write a mini app, you might say, "Oh, well, this one component, this real-time component, that will be challenging! That will be fun! I’ll get into that right now!" I mean, everyone in this room has had that moment where they spent hours, days, or weeks on something. Then, days later, you realize that it’s a pile of crap.
00:08:35.680
You realize there’s so much code you didn’t need that you could have outsourced to another library. You jumped too fast into the interesting part without considering what the end result should be, whether that be a public API or the ultimate web app. So, README-driven development: the first thing you need to do is put yourself in your user's shoes. How do they install it? What is the end product? What are you delivering them? For me, figuring that out helped me build something efficiently.
00:09:08.880
At that point, I just read my README as I’m building it, and it guides me. Secondly, READMEs are all over the place. They’re in the root of your directory, and they’re also on GitHub; we put the README on the front page of your repo, underneath all your code. It’s highly visible, and people love seeing well-written REAMEs. So go to town—do some cool formatting, put in images, whatever you want! This is the document that will impress people. If you can have this done first, it becomes the foundation of your project rather than the last thing you do before shipping.
00:10:17.120
A little pro tip: READMEs work in subdirectories, at least on GitHub. By that I mean, they show up if you go through directories and click into a subdirectory. If there’s a README there, it’ll show that README to you. This stuff is a bit hidden, but it’s fascinating. Rick Olson was writing Stratocaster at GitHub, an internal library to handle all of our events—like repo creation, issue comments, and stuff like that. It’s a big project but separate. You still need a hook into the GitHub code, so in lib/stratocaster he has a dedicated README detailing just Stratocaster stuff.
00:11:41.919
If a month or two down the line I figure out there’s a bug in this, I want to check it out, and the README is right there to help me only for that topic. That’s really helpful! So, give that thought if you’re ever working on something similar in the future. Everyone loves a good README—it’s a living document. Writing your README first doesn't mean you’re done; the best README is one that you keep building on. If you change your stuff down the line, change the README—it’s a living document!
00:12:38.960
By the end, it becomes a great document to have. Everybody loves a README; everyone hates a crappy README, and we've all been to those bad READMEs. So, let's talk about README-driven development. I want to shift gears and address something we all face. So, you might be refactoring something and see a no method error. You are obviously wondering what the hell these methods are, but you dig into it next. You might find a method call buried in an array and know that the third one must be nil. You dive into the next method, and it has three method calls inside an array. Something is wrong with what’s being passed in.
00:13:55.680
You go into the whiskey method and into another module for analysis. You analyze and pull up more code, and it’s a complicated mess! This is a contrived example, but everyone has encountered this scenario. You don’t want to reconstruct all these method calls in your head. We are not Ruby interpreters, and we should be able to rely on documentation to guide us through these situations.
00:14:25.839
This is where inline documentation comes in. For GitHub, this is huge. We’ve passed the stage of worrying about whether our business might collapse. We have a good idea of how to host Git repos and make money. Now, the main problem is continuing our growth while ensuring our code remains clean and easy to read. This is our top concern, and we’ve found that inline documentation really helps.
00:15:01.600
We use Tom Dock, which was invented by that guy again, Tom Preston-Warner. Tom Dock is a simple way to add inline documentation to your method calls. For example, you might see a fake method called 'add mustache' which is supposed to add a mustache to an image. This may or may not exist in various forms in the GitHub codebase.
00:16:10.480
Tom Dock tells you whether it’s a public method. From the start, you contemplate how to present this internal API to other users. If it's public, you label it as public; if it’s not, you denote it as a private method. It's crucial to differentiate between them. Secondly, Tom Dock lets you add traditional comments, giving a high-level, simple overview of what the method does. If the actual implementation is complex, this high-level overview helps clarify what the method is doing.
00:17:34.000
Next, you label your arguments. In this case, we’re passing in an image which is just a path to a local image on disk. When you're passing in hashes, it can be tricky to see the value they represent. You might detail if a hash is passed in and include the expected parameters and their descriptions. This creates a clearer view of what you’re passing into the method.
00:18:23.040
Then, you provide examples to show how the method works. Examples can be less important for some methods, but others—especially critical ones—should have plenty of examples. This helps you understand how to interact with the method without digging through the codebase. Finally, you need to describe what the method returns. Does it return a string, an array, or something else? Clarifying the output is another layer of understanding for the method.
00:19:05.120
So, that’s what Tom Dock is. Why is this important to us? First of all, it's plain text. I like Tom Dock because it’s similar to Markdown, which is easy to read without needing rendering. You don’t have to learn a new programming language to read documentation. This also works if you're using this in other languages.
00:20:09.520
Secondly, it’s in English. People know their native language much better than programming languages, and having a simple way to describe what a method does helps them understand how to use it. Finally, clear documentation helps alleviate the burden of mental interpolation between methods. You can look up what each method should do and the arguments it takes directly without needing to reconstruct everything yourself.
00:21:27.280
Tom Dock is flexible; it should fit around your needs. Don’t feel pressured to include something if it doesn’t make sense for a specific method. Most of my Tom Dock methods just include a one-liner detailing what it does and a return statement, which works just fine. The goal is to find a process that suits you and your context.
00:22:41.400
Let me tell you how this has improved my coding. When you're writing documentation, it forces you to consider what’s happening with your code. It becomes glaringly obvious when things are complicated. You find yourself reconsidering if you can break a code segment into smaller, clearer methods. Your methods become smaller and smarter over time.
00:23:32.640
Better documentation leads to better tests. As you adjust your documentation, it informs your tests better. If you have documents that detail specific scenarios, it's easier to know what to test against. Smaller and clearer methods translate directly into more intuitive and effective tests.
00:24:26.320
Every time we code, everything we touch ends up getting documented with Tom Dock; we’re 40 people now, which means we can't just push code and hope others will figure it out. Ensuring clarity is key at scale. The more communicative we can be with each other, the more robust our codebase is. This talk is somewhat of a rage reaction to a blog post I wrote back in June; usually when you post something controversial, you hear people say, "Documentation is nice, but I work differently." But this time, most reactions leaned towards not documenting anything even when they wrote tons of code.
00:25:34.240
I want to address some of those reactions. I think we've all been there: even if you feel confident about your code, that doesn't mean it won't confuse you months later. Code can be complicated, and the stuff you write today may be used for years ahead. It’s vital to have solid documentation to help future maintainers understand decisions behind the code.
00:26:45.040
We also need to start combating the notion that documentation is always stale. That shouldn't be the case—you should update documentation while updating code. This applies to inline documentation, READMEs, and wikis; whenever the implementation changes, documentation should reflect that change.
00:27:54.000
Though some might feel that extensive documentation is verbose or unnecessary, I believe the standard practices are worth the effort. Letting the tools and team evolve naturally means you will discover what works best—for you! Having your code next to your documentation ensures that it is directly available when needed, which aligns everyone for a better experience.
00:28:47.320
As we start wrapping up, if you have any questions, feel free to ask me. I’m Holman; I appreciate you all.
00:29:28.080
Oh, and by the way, there are no catcalls, please!
00:29:37.440
If anyone is up for some further discussion, I would love to engage! Whether it's about the process we follow at GitHub, how we utilize documentation, or the changes we’ve made over the years, feel free to tackle me with your questions.