Ruby Video
Ruby
A Documentation Talk
Zach Holman
@holman
#documentation
#ruby
#code-quality
#developer-experience-dx
#test-driven-development
#best-practices
Summarized using AI

A Documentation Talk

by Zach Holman

In his talk titled "A Documentation Talk," Zach Holman emphasizes the vital role of documentation in programming, particularly in Ruby development. He starts by highlighting the importance of communication and how poor communication leads to misunderstandings, both in personal interactions and in coding. Holman asserts that documentation serves as this essential communication tool in code, leading to faster, simpler code, and better project management.

Key points discussed include:
- The Role of Documentation: Holman insists that clear documentation is critical as it enhances understanding and efficiency in code management. At GitHub, comprehensive documentation is added for every method, promoting clarity and helping developers manage new commits without confusion.
- Selfishness in Documentation: He argues that documentation should primarily benefit the author, encouraging developers to write documentation that aids their understanding first, which subsequently helps others.
- README-Driven Development: He introduces the concept where developers begin projects by writing the README before any code or tests. This approach prompts developers to consider the end-user's perspective, leading to better project outcomes and clearer documentation.
- Inline Documentation: Holman discusses the practice of incorporating inline documentation for methods which aids in maintaining clean code and avoiding refactoring complications. He suggests clearly defining method functionality, usage examples, and expected return values to enhance clarity.
- Continuous Documentation: Documentation should be updated regularly as projects evolve. This practice ensures that documentation remains relevant and helps in maintaining code quality over time.
- Cultural Shift: Holman reflects on the cultural resistance to documentation, with many developers skeptical about its value. He counters this by sharing his experiences, illustrating the pitfalls of neglecting documentation, and advocating for a shift in mindset among developers.

In conclusion, Holman stresses that effective documentation is an ongoing process that saves time and effort in the long run, improves code quality, and ultimately aids in project management. Developers are encouraged to make documentation a priority and integrate it closely with their coding practices, thereby fostering an environment of clarity and collaboration within their teams.

00:00:07.839 Hello, everyone.
00:00:10.040 Audience, check out these shades. Pretty cool, right? Does anybody know why I'm on stage wearing sunglasses inside like an idiot?
00:00:15.560 Let me give you a hint: you don't know because I haven't told you. Communication is important. Without communication, and without me clearly telling you why I'm doing this, you're forced to ask questions and make assumptions, like: 'What's he up there for? Why is he wearing glasses? Is he being kind of a jerk? Is he hung over? Is he crying? What's going on here?' Mostly, it's that I thought it would make me look cool.
00:00:28.920 This is a point worth making: communication is important. Without communication, you have to go on these wild sprees and make things up for yourself. It's really inefficient, and this goes double for code. Code documentation is your communication in code, and documentation really is important.
00:01:00.960 This is what I want to talk about today. This stuff is crucial. At GitHub, we add documentation to every single method we write, and we couldn't be more excited about it. It means faster and simpler code, stronger tests, and developers can pay attention to new commits without stressing about them. Documentation will make your project very happy.
00:01:14.159 Let me tell you a dirty secret: humans are not Ruby interpreters. People often claim that they're developers and that their code is awesome no matter what they write. But that's not true. You can sort of stumble through, but sooner or later, if you've spent years writing Ruby, you will be better at reading English or your native language than at interpreting code.
00:01:21.960 This is why I think documentation is essential. So I'm Zach Holman, I'm Holman on Twitter, and I'm homman on GitHub. Right now, I'm drinking a fine Boulder beer. So if you throw your tomatoes, don’t ruin the beer! I do work for GitHub, which is like a code host, sort of like SourceForge.
00:01:44.360 I know that many of you like Twitter, and I expect you to have the Twitter backchannel during my talk. I know you're going to talk about me behind my back, so I'd like to consolidate all that into one hashtag for this talk. Make sure your punctuation has been chosen quite well, considering this hashtag is 139 characters long.
00:01:53.160 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 is the big deal about all this?
00:02:00.960 You may despise documentation. Maybe I’m not the right person for this talk, because, honestly, I have hated documentation in the past. It felt like too much process. I hate process, meetings, and anything that gets in the way of me doing actual work. Any sort of upfront planning felt useless to me.
00:02:11.600 But most importantly, I never liked to help people. I think this is an important point. If what I do ultimately helps people, that’s great, but I want it to help me first. If that side effect happens later, that's awesome, but I won't do something unless I find a direct benefit to myself. That's a mentality I encourage for any sort of development: if it's going to help you, then you're going to do it.
00:02:40.600 Documentation should be selfish. I don't think that's a bad thing to say. As long as you get into a system you're comfortable with, that’s a good thing. Today, I found three main ways documentation has helped me the most. First and foremost, documentation has improved my Ruby code significantly. I know many people who sit at a keyboard and just type code that flows beautifully.
00:03:00.960 I, on the other hand, struggle with my code. Beautiful code does come out of my fingers at times, but it takes a lot of thought and consciousness. Documentation has helped me improve the way I write code, and I’ll elaborate on that later.
00:03:26.760 Secondly, better Ruby leads to better tests. Writing documentation helps me understand what I need to test and what edge cases should be considered. I’ll discuss this further, but first, I want to talk about projects.
00:03:41.760 I love projects! I write lots of small Sinatra apps and little gems. I enjoy the idea of doing small projects and shipping them quickly. So, I want to find a way to produce really good projects as fast as possible. This leads us to discuss README-driven development. This concept was mentioned a little bit yesterday, and I will dive deeper into it today.
00:04:04.680 README-driven development was influenced by Tom Preston-Warner, one of the co-founders at GitHub. I find this concept interesting and beneficial. Here’s how it works: Step one, you write your README. Step two, there’s no step two. I apologize for that terrible joke, but that’s really all there is to it. You sit down and write your README, detailing things like installation steps, how the public API is structured, and any to-do items. You write that README first, even before writing any code or tests.
00:04:32.120 This is why developers have the tendency to think of a cool project idea. The first thought is usually the most interesting part—like a flashy one real-time component of the app. We've all been there, diving right into that interesting component only to realize down the line that we spent a lot of time on a feature that wasn’t needed. You should always consider the entire end product, whether that’s a public API or any web app.
00:05:00.720 With README-driven development, the first thing you do is put yourself in the user’s shoes and consider how they will install it. What is the end product? What am I delivering to them? This mentality helped me construct better projects.
00:05:15.600 Moreover, READMEs are everywhere. They serve as the root document of your repository, and on GitHub, we present the README right on the front page of your repo, underneath all the code. People appreciate well-written READMEs, so put in the time to create a cool-looking format, add images, or any other enhancements. It lays the foundation for your project rather than being an afterthought before shipping.
00:05:45.000 A small pro tip: READMEs work well in subdirectories on GitHub. If you have a project with multiple subdirectories, the README for each can be shown when navigating through them. This capability is beneficial for larger projects. For example, Rick Olsson developed Stratocaster, an internal library at GitHub to handle events like repository creation or issue comments. In the lib/Stratocaster directory, he included a README that details only the Stratocaster content. This feature is tremendously helpful, especially when addressing bugs down the line.
00:06:24.840 Secondly, a README is a living document. Just because you write it first doesn’t mean it’s done. You should continue to refine and update it as needed. If you change something in your project, ensure that the README reflects those changes.
00:06:55.840 A good README always stands out; everyone hates a poorly constructed README, and all of us have experienced those rotten READMEs. So, let’s shift to a slightly different topic now. A problem we all face is encountering a no-method error during refactoring.
00:07:29.600 You might recognize this when you try to dig into what the method should do; you realize it’s poorly structured. We’ve all experienced it. It often leads to reconstruction work in our minds where we have to understand all these method calls. Yes, we can do that, and we’re reasonably smart, but it shouldn’t be the case.
00:08:12.320 This is where inline documentation comes into play. For us at GitHub, inline documentation is significant. Once we passed the early stages of our business, we established a good idea of how to host git repositories and make money. Now it’s crucial to maintain growth and ensure our code remains clean and easy to read.
00:08:36.640 One of the best practices we’ve adopted is inline documentation. This approach has allowed us to communicate effectively within our team and maintain a stable codebase.
00:09:00.720 Consider an example: adding inline documentation to method calls using the ‘TODO’ method invented by Tom Preston-Warner. A simple method called 'add_mustache' adds a mustache to an image. In this case, your first step involves determining whether it's a public method.
00:09:35.840 This contextualizes how to present this internal API. If it's public, we indicate that; if not, we treat it as a private method. Secondly, providing a high-level overview that explains what the method does can be helpful—especially if the implementation is complex.
00:10:14.480 It becomes essential to label your arguments clearly. For example, if your method receives an image as a string path, clarity on what you expect the arguments to be adds value. This clarity is vital when passing hashes in Ruby, where knowing the contents of the hash is crucial.
00:10:47.680 Moreover, including usage examples in your documentation can clarify things further. Some methods necessitate extensive examples to emphasize correct usage, while others may not require at all, depending on their complexity.
00:11:22.560 Finally, make sure to specify what the method returns—whether it’s a string, an array, or possibly both, depending on the input. This explicitness helps convey to end-users what they should expect, making the documentation much more effective.
00:11:54.120 Why is all this important? First, because it’s plain text. You don’t need to render it or learn a different language—similar to markdown. It communicates in a straightforward way, and this works across various programming languages.
00:12:20.040 Secondly, because it’s using English—your native language. It’s easier for people to understand and allows a simple way to describe what a method’s purpose is and its return values.
00:12:43.200 Importantly, this documentation is explicit. It prevents misunderstanding in your code. It supports effective communication when interpreting API or method usage directly, which can save time troubleshooting both implementation and documentation.
00:13:07.560 Additionally, the flexibility offered by something like the ‘TODO’ method is beneficial. It doesn’t force you into a rigid format. If you don’t feel the need to include examples or details about arguments, you can choose to simplify it. The focus should be on ensuring effective communication.
00:13:29.200 Ultimately, you want to establish a process that works for you and adapts to situational demands. I’ve emphasized that documentation helps improve coding quality. With smaller 'TODOs' or smaller methods, you're forced to identify what's actually happening, which may lead to splitting larger methods into smaller, more manageable pieces.
00:14:14.000 By writing documentation frequently, you will end up producing better tests. The better your Ruby code is, the more effective your testing will be. As documentation leads to clearer code, it furthermore simplifies the identification of edge cases and guarantees that they are well-defined in your tests.
00:15:00.920 And as for project management methodologies, we have adopted the ‘TODO’ technique in all the languages we use, including Ruby and JavaScript. Our team continues to implement this approach, and as the company scales, clarity and communication are essential for maintaining code quality.
00:15:37.440 Moving on, this talk originated from a reaction to a blog post I wrote in June. Typically, controversial blog posts receive mixed feedback, and you can expect various takes on documentation approaches. In this case, however, responses emphasized how documentation isn't valuable, and many felt confident that their code was perfect without it.
00:16:18.560 This perspective surprises me; I have code I’m proud of one week that I look back on the next and have no idea what I was thinking. Code can quickly become complicated, and considering that your work may last for years, having a robust documentation foundation is critical for efficient project management.
00:16:57.760 Let's debunk the misconception that documentation is always stale. Documentation should evolve alongside the implementation. Whether for inline comments, READMEs, or wikis, it’s vital to maintain documentation to meet ongoing code changes. One should never skimp on documentation just because the implementation changes!
00:17:33.600 Verbose documentation might seem cumbersome, but the practice becomes a habit that improves overall process efficiency. If you find it unnecessary, simplify wherever you can, but recognize that keeping a strong documentation habit will ultimately save you time in the long run.
00:18:05.240 Lastly, people often misplace their intentions, mistakenly believing that their commit messages or tests contain all their original intentions. However, realistic practices show that no one analyzes all commit messages or tests after coding. Instead, having documentation linking code to its explanations is essential for clarity.
00:18:40.400 This importance resonates with us at GitHub, and we actively promote strong communication through effective documentation. I encourage you to seriously consider those thoughts and find a way that works for you with regard to your documentation practices.
00:19:09.480 Questions? I’m Homan, ask me anything.
00:19:25.840 Thank you.
00:19:35.760 Yes, a question was posed. Were we always using ‘TODO,’ or did we migrate from something else?
00:19:43.200 ‘TODO’ formally started amidst a small group of active developers within the codebase. It wasn't like we started with a predetermined structure. Instead, about a year into development, we began integrating this method, and now we've reached a point where there are still some areas lacking documentation; it’s just as important as writing the implementation code.
00:20:45.040 The optimal method of improving documentation for developers on a team facing tight deadlines is another valid concern. Often, it appears to me that the practices I’ve shared today leverage minimal additional time commitment. You just need to approach writing code and documentation together rather than sequentially performing one after the other.
00:21:28.000 Documentation and code writing can occur in synergy, allowing for easier project management and improved outcomes on deadlines. It’s true that maintaining this balance can be challenging, but embracing it fosters collective development practices and to some degree enhances communication and code comprehension. So, feel free to take advantage of this.
00:21:54.760 Do you have a specified process for updating documentation when you change your implementation?
00:22:06.760 Absolutely! Each time we modify a piece of code, we update its corresponding documentation to maintain consistency. If you find someone altering the code without adjusting the documentation, it’s crucial to intervene and emphasize the interrelation between these two aspects. The documentation remains relevant, as it’s naturally located near its respective code, significantly aiding in keeping both aligned.
00:22:44.760 The scalability of READMEs can sometimes raise questions about their allowable size. Tom Preston-Warner initiated README-driven development on Gollum, which supported large README files. Discussions about splitting content between primary README files and wikis have also emerged, as this practice may enhance clarity on specific aspects of a project.
00:23:23.880 You should not shy away from creating lengthy, informative READMEs filled with crucial content if it serves your project's needs. A comprehensive documentary offers value, particularly if it stays relevant to addressing user needs effectively.
00:24:00.560 Finally, the concept of merging documentation with testing has been explored but not executed due to existing best practices within the Ruby programming community. Though it seems appealing to combine the two, practical implementation would pose significant challenges.
00:25:00.760 In light of the current practices, I encourage those of you involved in documentation work to standardize your processes and ensure that all written documentation remains maintainable and straightforward. Emphasize the significance of continuous learning and adapting processes that won't cause you setbacks.
00:25:50.760 Thank you all for your attention, and feel free to ask any more questions if you have them!
Zach Holman
@holman
Edit
Explore all talks recorded at Rocky Mountain Ruby 2011
+14