 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've not told you Communication is important and without communication without me explicitly telling you why I'm doing this thing You're forced to ask questions and make assumptions like what's he up there? Why is he wearing glasses? Is he kind of a jerk or is he hung over? Is he crying? What's going on here? Mostly, it's I thought it would make me look cool But This is for a point like communication is important without communication You have to go on these wild sprees and make up things for yourself. It's really inefficient and this goes double for code code documentation is your communication in code and and documentation is important More or less and that's what I want to talk about today. This stuff is really important. This is what we do at github Let me tell you the dirty secret Humans are not ruby interpreters People like to say that like yeah, I'm a developer my code is awesome no matter what I write I can easily see like everything what I need to know. That's not true Yes, you can sort of stumble through but no matter what if you've spent five ten fifteen years writing ruby If you've been writing code since 1970 I guarantee you're gonna be better at reading English or reading your language native language or writing that And that's why I think documentation is really important. That's why I want to talk about today So I'm Zach Holman. I'm Holman on Twitter Holman on github. I am drinking a fine bolder beer So if you throw your tomatoes don't ruin the beer. I do work for github I guess it's like a code host or something It's like source forage Sort of I Know you guys like the Twitters. I know you're gonna have the Twitter back channel during my talk I know you're gonna talk about me behind my back So I'd like to consolidate all that into one hashtag for this talk. So this is the hashtag It's a hundred and thirty nine characters. So make sure your punctuation has been chosen quite well So let's get into it if you're like me you're gonna that's the wrong question to ask Why should we do this shit if you're thinking about documentation? Why should you do this? what is the big deal about all this stuff and I Hate documentation Maybe I'm not the right person for this talk. I'll wing it. I don't like documentation. This is me circa like a year ago The main reason I didn't like documentation because it felt like a lot of process It felt really heavy and I hate process. I hate meetings I hate anything that gets in the way of me doing actual work and it really feels like you know 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 And this is this is kind of the important thing like this is how we're all Sort of like this and like yes if if what I do ultimately helps people That's great, but when you come down to it like I don't want to do something for my manager I don't want to do something for users like first and foremost I want it to help me and if that stuff happens down the line That's great, but I'm not going to do something unless I find direct benefit to me And I think that's important if you're looking for Any sort of development mentality of if it's going to help me and then then you're going to do it So documentation should be selfish. I think that's really important. I don't think it's a bad thing to say I think as long as you get into a system that You are comfortable with I think that's a good thing So these are the three things that I found documentation be helping me the most and these are what I'm going to cover today First and foremost this stuff has helped my Ruby a lot. I know a lot of people who They they get to the keyboard and they start typing code and just like beauty flows from their keyboard and like in like out Of their fingers and stuff I get to the keyboard and just like sewage runs through my fingers into the you know Them or whatever I'm using and I can write beautiful code. I really can but it's really difficult for me I have to really think and I have to be conscious about like how is this going to be designed? How am I actually going to tackle this and documentation in a variety of different ways has helped me write better code I'm going to talk about that a little bit later. Secondly test when you have better Ruby you a better test and documentation The act of writing documentation has helped me really figure out. How do I test stuff? How what edge cases do I want to test? The whole gamut of that stuff don't get in that later, but first I want to talk about projects. I love projects I Write lots of little Sinatra apps right little stupid gems. I write Ruby libraries, you know a whole slew of things And I really like the idea that you can do really small projects and ship them and you know have a good time So it was important for me if I could find a mentality that would work and help me produce really good projects as fast as possible That's an ultimate win for me So I want to talk a little bit about read me driven development and this was mentioned a little bit yesterday And we'll dive into a little bit more today Read me driven development was invented by this guy Jesus This is frightening we're gonna find a little bit better photo for him So this is Tom Preston Warner mojombo. He's a co-founder at github. So he's one of my bosses Which is why I'm talking about it. We get docked pay unless we have free No, I'm just kidding. I'm talking about this stuff because it's really cool And this is really changed how I work and how we work at github So read me driven development step one. You're right. You read me step two It's no step two. I really apologize. That's the worst joke ever and everybody uses it, but I couldn't help But that's really all there is you you you sit down you write read me you write You know installation steps you write how the public API is going to be handled or how You know different to-do items or whatever you want to write for a good read me You just write that first the whole thing before you write a lick of code look of tests anything else This is the reason why Developers have this thing where if you have a cool project idea The first thing that you think of is the most interesting part if you're gonna write some sort of like you know mini app You can say oh well this one component this real-time component. I mean that will be challenging that'll be fun I want to get into that right now I can like do some cool inheritance and like go crazy and everybody in this room is at the time where They did something like that and then they spent hours on it or days or weeks and then like you know days or weeks later You realize that's a pile of horseshit. There's so much code. I didn't need that I could shell out to another library and I didn't it was you jump too fast into the interesting part And you didn't think about what the end result is be that a public API or you know the ultimate web app or anything like that so read me during the development you are You're the first thing you do with that is put yourself in your users shoes like how do you install it? What is the end product? What am I delivering to them? And that's that's for me that was really important to figure out How do I build something because at that point? I just read my read me as I'm building it and it just tells me what to do Secondly read means are all over the place I mean they're your root of your directory, but they're also on github We put the read me in you know the front page of your repo underneath all of your code And it's really visible people like seeing well-written read me So go to town like do some cool formatting put in images put in you know whatever you want This is the document that will be there that will impress people and if you can do that first I mean it's just just it becomes a foundation of your project rather than the last thing you do before you ship it Secondly, this is the little pro tip Read me is working sub directories at least on github and by that I mean they show up if you're going through directories and you click through your sub directory sub directory We'll show the read me if we find one for that sub directory and that stuff is kind of hidden and it's really interesting Rick Olson was writing Stratocaster at github as internal library to handle all of our events like repo created Issue commented on stuff like that all of your news feed items And it's a big project and it's a separate project, but you need a hook into the github code So in like lib slash Stratocaster, he has a separate read me detailing just the Stratocaster stuff So if a month or two down the line, I figure out well, there's a bug in this I want to check it out the read me is right there and it's contained just to that topic and it's really helpful So give that one a thought if you're working at something similar in the future Everyone loves a good read me. It's a living document Writing you read me first does not mean you write it and then you're done Like it the best read me if you do it first you keep building on it If you change your stuff down the line change your read me It's a living document. It wants to be changed and then by the end of it It's a great document to have everybody loves a read me Everyone hates a shitty read me and everyone has been to those shitty read me's So let's read me read me driven development I want to go on to a little bit different topic right now and first I want to dump and jump into a problem. We have all sort of faced stuff like this So you see like this you're refactoring something and you see like no method error and you are Obviously wondering what the hell these methods are but you know you try and dig into that next So digging that method and you first realize this is a terrible method You should probably factor this but you know, we're trying to figure out how to fix this So first, you know, we see that there's a method column and you call in a third in the array And then you call tonight So obviously the third one has got to be nil so you dive into this next method This next method all that says three method calls inside of an array So there's something wrong with whiskey that passes in tab you go into the whiskey and then it goes another Module that has analyzed you analyze the tab that you go in the module and then there's just more code You have to deal with all this shit. It's insane. I mean, it's a contrived example, but everybody's been into this sort of stuff where You you you have to reconstruct all of these method calls mentally and yes, you can do that That is not a big deal where humans were reasonably smart But you shouldn't have to It's it's we are not Ruby interpreters and We should be able to rely on something else that tells us how to deal with all of this stuff instead, so That's where in line documentation comes in For GitHub, this is really big for us. We're past the point of the first year to where Our business may collapse. We have a good idea of how to host get repos We are have a good idea to make money stuff like that and it's very unlikely in the next two or three years like Suddenly it will just not work. There will be problems, obviously But we're in a different stage of our development where now the big problem is how do we continue our growth? how do we have code that is clean and still worthwhile to read and doesn't slow us down like that's the number one concern And we've done pretty well at that and one of the best things we've done is in line documentation Which we will get into because we use Tom doc, which is invented by All right, but about that guy again Tom doc Tom Preston Warner Tom doc is a very simple way of adding in line documentation to your method calls For example, this is just a fake method called add mustache Adds a mustache to an image. This may or may not exist in lots of different ways in the github code base No comment So basically this is your simple method and then assume it does something cool in there This is the Tom doc for it. So let's step through this real quick first is the You say whether or not it's a public method So from the start you are contemplating how do I present this internal API to other users if it's public You say public if it's not just a minute and it's considered a private method and it's it's important to denote that stuff Secondly add the so the traditional comment you may add to a method in terms of just describe it Give it a high-level language really simple overview of like how does this work? This adds a mustache to an image pretty simple if the actual implementation was really complex That's really helpful to figure out what the hell this actually does you actually have to read code Humans are better at this than reading code Secondly, you let you label your arguments. So in this case we're passing in an image Which is just a string path to a local image on disk this It can sometimes be tricky to see the value in this But consider the point when you're passing in hashes Which is what rubious do all the time and you have like the question of is this value going to be in this hash? Is this value going to be in a rate in this case? You would detail, you know if there's a hash passed in say this is the hash And then you detail like this will have the name parameter have the url parameter to have all this other stuff And you have a very concrete Detailed view of what you're passing into this method Next you have examples Just show how you do it This is This can be really important it can be less important some methods You don't actually have to have this block we have some methods in github where we'll have Like a two or three line Internal method that's really important like it actually handles your repositories on disk and we'll have 10 12 13 examples of how to deal with it because it's so important You don't want to have to deal through the code base to try and figure out where have I done this before and Can I just copy and paste that in? This is the best place to say it if you're passing in a string here. This happens if you're passing in an array here This happens It can be incredibly important to have this sort of concrete examples right there right in the middle of code that you're going to be using And then finally Just tell it what it returns does it return a string does it return an array? Does it return a string or an array depending on the input if it's a hash detail the hash It's just another way of figuring out explicitly. What is happening in that method? So That's what Tom doc is. Why is this important to us? First of all, it's plain text I like Tom doc because I like Tom doc in the same way. I like markdown Markdown is you know, you don't have to render it to really figure out what is happening You have you know italics and stuff and you're like obviously that's probably important But it's not interrupting how I read it the same way with Tom doc I don't want to hate on like our doc or anything like that If you're using that that's great. It's just the same thing, but a different flavor for me I really like the idea that there's no hidden like Internal method calls and stuff like that that you have to learn you don't want to have to learn a new language to read documentation This also works if you're using this in other languages, too Our doc will not transfer to JavaScript as well Secondly, it's English. This is what I was talking about earlier people know their native language a lot better than they know programming and just having a You know simple way of describing this is what this method does a simple way of figuring out This is what this method returns and examples all of that stuff helps you figure out what this method actually does and how you can use it Finally explicit Also important. I mean this is how you avoid the whole method chain interpolation in your mind. You can just just Reassure yourself that the documentation is telling you what you should be expecting and then you can look in there and be like Oh, well, this is not returning the right thing and then you can attack that method directly The same thing with arguments just having those detailed having the hashes detailed when relevant is just super important and flexible this is the other thing that like For me Tom doc is really awesome because it's really flexible It's not trying to dictate some sort of dogma If you don't want examples don't include examples if you don't want to do the arguments Don't do them if it's just too simple if you should figure it out on your own Just don't do them most of my time back methods are just the top line what it does and then space and then the bottom line What it returns and that's perfectly fine The point is to find something that works for you and in each case what works best for that case So I was telling you what this is how this has improved me as a coder So in terms of Ruby, how does this make it better tiny methods if you're writing Tom doc or any sort of documentation? You're forced to figure out what's actually happening in this method and it's it sticks out like a sore thumb if you're going through and you're typing all The stuff like well, you know in this case this returns this or this returns this and it's like it's really complicated And as you're typing that you're realizing this is insane Why don't I split this up into like six seven eight methods if need be or two methods? and it just becomes a lot better you have tiny methods it's very clear and You just have to deal with less overhead mentally along those lines you have smarter methods you have You know, why would you want to document this like seven parameter hash if you don't have to? It forces yourself to think like maybe I can pass in just a string argument Do I actually need the whole data model there? Can I split this up a different way? It's just another step of saying how can I do this stuff better than I currently am? tests better Ruby code leads to better tests and All of the stuff that I just said means you're gonna have better tests you have smaller methods You have more concrete methods. They only deal with specific items that they're concerned with It's just a lot easier to write tests No, as you're in your put output if you're talking about like what is inputting if you have some crazy hash inputted That translates to a test a lot better You don't have to actually have to think like oh, where is this called from what's getting sent in? You just look at the docs and then write the test from there Same thing with education cases. They stick out like a sore thumb if you have a conditional in there And you're saying like well, you know if this is nil do this differently Those should all be test cases that translates very well between implementation to documentation to test So I mean we do Tom doc a lot and we do our Ruby we do like JavaScript I mean everything that we touch ends up being Tom doc because it I mean we're like we're 40 people at this point And it's we're getting too big to be able to just push code out there and expect other people to figure out What's going on because there's lots of edge conditions when you're at the scale that we are And the the more communicative we can be to each other The the the stronger the code base we ultimately have So this talk was sort of a rage reaction to a blog post ahead in june And usually if you do like a controversial blog post you get the sort of response We're like yeah, I mean documentation is all right, but I kind of do this other way Apparently on this blog post people are mostly like yeah fuck documentation. I don't document anything I write 200,000 lines of code. It's all perfect And then they walk off the stage because they're on a stage um I don't understand I want to talk about some of the reactions to some of this my code is perfect I think that's bullshit. I have stuff that last week. I'm proud about and I see this week And I have no idea what I was doing. I mean we've all been there like it's it's Code is complicated And the stuff you write today may be used for the next two years It's important that you have a good foundation of how that code is done And you just go from that point forward No, no one updates documentation. This is a big deal. Um, this is true In some regards this should not happen We got to get away from this perspective of Documentation is always stale that shouldn't happen because you should update documentation as you update the implementation This is the true for inline code Code comments. This is true for readmes. Um, this is true for wikis anything you have to end up doing You got to get away from the idea that changing implementation means you can skimp on documentation. That shouldn't happen to verbose It is verbose If you start writing stuff like this like tom dock in particular It is verbose, but it's something that you cling on to because it's a standard practice that you get into the habit and again, like if you come into the idea that you don't need a An example in everyone. That's fine. Just do it how you want to do it The important part is figuring out a process that works for you Um, and you know if you don't want that verbosity everywhere, just don't do it finally People have their intentions in weird places that like I put all of my intentions in my Get commit messages. Therefore I can go back and check them out or My tests are my documentation. I have all my edge cases all of my you know different concerns I'm dealing with therefore I check my test. I think that's bullshit. No one does that No one looks through the whole test because your test file could have Tests for the same method in totally different places because it's broken out by different concerns No one looks at no one runs git log to try and figure out what some ways an original intention is They like to say they do but they actually don't what you want to do is have your code Next to your documentation. So it's right there and you can actually look at it This stuff's important to us Again, like this is what's making github as stable as it is right now We really push hard on this And we're really happy with it. So I want to encourage you to At least give it a shot like I'm a big proponent of Antidogma and all this stuff for me test-driven development, you know BDD Agile all that stuff never worked for me because It just didn't and I recognize that it works for tons of other people And if that works for you, that's great. If this stuff works for you, that's great as well And I just think that we need more documentation stressing We need to stress documentation in more places than we do currently. So That's what I got any questions. I'm holman asked me I love you guys cat calls. Yes Um question was was it always tom doc or we moved from something else? Um tom doc sort of started um Seriously, maybe like a year into the code base, I think which meant that there was probably I don't know five or six active developers on the code base. So there was less Structured anything. Um, we never started in our doc or anything like that. Um And then about a year or like two years ago at this point We started Adding more and more and now we get to the point where like we still have lots of places that have no documentation And you know, if you see that add them now and it's just as relevant as adding Implementation code to tom doc originally I believe this the the wording was linus has linux. Therefore. I should have tom doc Can't fault the man Yes, redshirt aisle So the question was uh, what's the best or what's the single most important thing to To help your developers improve documentation for the team So relevant to client was the rest of the question. Um working with clients I mean, I have to do this from the perspective of I work in product And we have the luxury. We have no deadlines at github. So that's a bit of a benefit And we can do stuff like this. I don't feel like any of the stuff that I've mentioned today really takes that much more time um I never sit down and spend an hour on tom doc And I feel like it's it just seems to go hand in hand with code If you're going to write the code just write the docs and it's not that much further and You know more often than not I find that I save a lot of time writing that up front And then writing the code then going down the rabbit hole writing terrible code and then having to fix it later Yes So the question is what is the process of writing this stuff? I I don't subscribe to anything. Um, sometimes I'll I will uh do the entire module or class and Do all the methods and then tom docket and then you know, sometimes I'll write the test then and then I'll go back And write the implementation after all that sometimes I'll just do the methods first and then Docket later do test later. Um, I'm not a stickler for any of it really It's just up to whatever makes sense in that situation. What you're comfortable with second question I'm already on top of it I tomdock that response Yes There are a couple. Um, chris wandsroth wrote one a while ago um I think I mean my opinion on that and tom's opinion on that is more of We find a less interest The the reason for tom doc is more you're diving into the code of somebody else's library How do you understand it best not like uh, like a generated View of somebody's documentation code. Um, and there's certainly ways to do it. Um Yard has a tom doc generation hook, I believe. Um, but that that In some respects it almost seems a lot different use case than What it was originally intended for Yes Yes, um, you would want generated code for stuff like rails. You're saying or generated docs I feel like generated docs are only more helpful for Things that I don't dig into the code for where I'm just totally an end user like ruby like rails And then if I'm using something like omnia More often than not I go straight into the code and I feel like it's sort of less helpful to look at a generated listing of docs based from like A small library like that. Maybe that's just me but yes Yeah, so the question is uh Do you have a process for changing or updating documentation when you change the implementation? That is the process when you update code you have to change the docs and like it's worth We're just a stickler for it for that. Um, and if you see somebody changing something without changing the docs you yell at them And it's usually not the big of a deal But it is sort of a mental mode that you have to get into where those two things are linked And it's usually not that bad because they're literally on top of each other A what an operative what? Upward limit for readme sizes no one of my favorites is uh, uh, uh, tom was actually First starting readme driven development on golem, uh, the get backed wiki on get up and it's it's a massive readme And I've gone back and forth it was actually we were talking about this in the danger room on campfire about like Where do you break stuff out of the readme into the wiki and Just throw everything into it Yeah, um I I go back and forth. I think some things like wikis make a lot of sense if they're totally Outside of the scope of readme on the other hand. I love just a fat readme that just goes for pages You just like you know command f and look what you're finding what you're looking for and I'm cool with that so the question is sort of emerging tests and comments in some fashion um Yes, we've thought about that More from like wouldn't that be cool? But it never seemed like a feasible way to do that because there's so many best practices in ruby already cool Thank you