Ruby Video
MountainWest RubyConf 2010
Documentation and the Whole nine YARDs
Loren Segal
@lsegal

Documentation and the Whole nine YARDs

by Loren Segal

In a talk titled "Documentation and the Whole Nine YARDs," Loren Segal addresses the critical role of documentation within the Ruby community during the MountainWest RubyConf 2010. Rather than focusing on the specifics of YARD, the Ruby documentation tool he developed, Segal underscores the broader significance of robust documentation in software development.

Key Points Discussed:
- Purpose of Documentation:
- Documentation is essential for helping users understand code behavior and can illuminate potential flaws in API design. If explaining a class or method requires excessive detail, it may warrant a redesign.

  • Current State of Ruby Documentation:

    • Segal highlights the inadequacies in Ruby's core and standard library documentation, using examples such as SignalException and DBM classes which lack clear information. Poor documentation can lead to serious issues, as illustrated by a Rails security vulnerability stemming from misleading guides.

  • Developer Responsibility:

    • During a poll, it was noted that while many write libraries, fewer prioritize good documentation practices, often citing a lack of time. Segal argues that documentation should be integrated throughout the development process rather than treated as an afterthought.

  • User Frustration and Self-Documenting Code:

    • He stresses that neglecting documentation can frustrate users, necessitating a shift in mindset from viewing code as self-documenting. Increasing code complexity in fact makes documenting more essential.

  • Strategies for Effective Documentation:

    • Segal outlines key principles for producing quality documentation:
    • Consistency: Maintain a cohesive style throughout.
    • Correctness: Regularly review and ensure documentation is accurate.
    • Coherence: Documentation must be understandable to someone without deep knowledge of the code.

  • YARD's Role:

    • YARD is designed to facilitate better documentation through standardization akin to Javadoc, offering features such as parameter and return tags, as well as tools to ensure documentation quality. It allows for clear navigation and provides features that make documenting easier.

  • Improving Documentation Practices:

    • Continuous improvement is emphasized, with Segal encouraging developers to adopt better documentation practices and consider contributing to the improvement of Ruby's standard library documentation.

In conclusion, Segal calls for a collective effort in the Ruby community to prioritize and enhance documentation practices, which would lead to more satisfied users and better software development outcomes.

00:00:16.640 Hello everyone, I'm Loren Segal, and today I'm going to discuss documentation in the Ruby community. Before we dive in, let me clarify who I am. I blog, I tweet, and of course, I use Ruby. Most importantly, I developed a tool called YARD, which I hope some of you have used or at least heard about. YARD is a Ruby documentation tool, and you can find it at yardoc.org.
00:00:40.320 But the truth is, I don't want to focus on YARD today. I'm not going to delve into the technical details of how YARD works. Instead, I want to address the overarching topic of documentation in the Ruby community. I aim to encourage all of you to take documentation more seriously. It's not just about YARD; it's about the broader perspective on how we treat documentation as part of the development process rather than something we do as an afterthought.
00:01:30.720 So, why is documentation important? Firstly, it helps users understand what your code is doing. There's an interesting side benefit to explaining your code; it can reveal flaws in your code and help you improve your API design to make it more user-friendly. If it takes you more than a few lines to explain a class or method, it might be worth reconsidering both its design and implementation.
00:02:06.080 Moreover, good documentation is increasingly hard to find. There's a notable problem within the Ruby community: much of our documentation, particularly for Ruby core and standard libraries, isn't up to par. For instance, the documentation for the SignalException class—an important class—consists mainly of a cut-and-paste from its superclass. Users unfamiliar with UNIX may not comprehend what it does.
00:02:49.280 Another example is the DBM class, which many people may not even know exists, although it's included with the Ruby standard library. The DBM class is not well-documented, which is a significant issue. We must improve documentation for our standard library as well as the core.
00:03:17.760 When documentation is poorly executed, the consequences can be severe. Take, for instance, a security vulnerability in Rails last year regarding HTTP digest authentication. The documentation incorrectly stated that returning nil would block the user, when in fact, it allowed access. This led to some serious implications for applications that employed those instructions.
00:03:58.080 Upon resolving the issue, developers needed to reflect on their risk management strategies to prevent such oversights in the future. The general consensus is to pay better attention to our documentation and review it thoroughly. YARD offers several features that can assist in identifying and fixing such problems.
00:04:45.040 Now, let's take a quick poll. Who here writes libraries or frameworks used by others? (A significant portion raises hands.) And how many of you emphasize documentation when writing those libraries? (Fewer hands go up.) In my experience, the number of people utilizing YARD remains relatively small compared to those employing RDoc. But this does not reflect the quality of documentation being produced.
00:05:34.440 So why is this the case? One underlying issue, often unspoken, is the belief that people do not have enough time to dedicate to documentation. My response is that we must prioritize this; documentation should not be an afterthought relegated to spare moments after completing feature implementations. It should be integrated into the development process. As we work on features, we should also be documenting them. This is ideal, yet it represents how we ought to handle this.
00:06:15.920 Why does this matter? Because neglecting documentation can anger users. Happy users are preferable, but avoiding user frustration is a higher priority. If a user has to sift through source code to figure out how to use your library, they might as well attempt to write it themselves. Moreover, many people assert that their code is self-documenting. I disagree with that notion.
00:07:07.360 Self-documenting code can become overwhelming when complexity increases. Refactoring does not reduce complexity; it merely shifts it to another layer. This complexity can be troublesome for users who lack understanding of those layers. Coding practices, such as using option hashes, can sometimes obscure important information, making it difficult for users to understand their options.
00:08:02.400 Many developers also claim that documentation is hard to write. I can accept that. However, it is essential for us to understand what makes documentation effective. There are a few fundamental principles that outline how to produce good documentation: First, ensure consistency. Documentation should reflect a cohesive style to avoid confusing users. If a method can raise an exception, state that clearly. If another method can do the same but isn't mentioned in the documentation, users will become confused.
00:09:15.840 Secondly, focus on correctness. Documentation can be incorrect much like code can be. We need to acknowledge that documentation requires review, auditing, and testing, akin to our code. Lastly, coherence is crucial as well. Documentation must make sense to someone without intimate knowledge of the code. The person who wrote the code is often the worst candidate to document it because they are likely aware of all the nuances that others may not understand.
00:10:40.000 To assist in overcoming some of these challenges, I created YARD to facilitate the documentation process. Its goals align with providing effective documentation through consistency, correctness, and coherency. Extensibility is also an inherent feature of YARD’s design. To achieve consistency, YARD employs a style similar to Javadoc, including parameter and return tags that are commonly used in languages like Objective-C, Java, and Python.
00:11:32.800 This is not a revolutionary idea, but by standardizing documentation, YARD can consistently extract information and present it across various formats. Also included is a focus on type information, which directly contributes to improved correctness.
00:12:00.640 YARD also makes it possible to test the quality of documentation. Returning to our earlier example regarding the Rails vulnerability, the development team could have included clear tags within their documentation to ensure proper configurations were communicated and therefore tested. DataMapper is a great example of effective documentation efforts, supported by a tool called yardstick that ensures correctness.
00:12:34.080 While coherency is ultimately the responsibility of the developer, YARD supports you by making documentation templates easy to read. The hierarchical class list allows for clear navigation through the namespaces, and YARD presents method parameters and return data in a structured and coherent fashion.
00:13:35.760 As a result, YARD documentation provides not only clear references but also a full inheritance tree for classes. Unlike RDoc’s limited view to just the parent class, this provides greater insight into class structures and relationships.
00:14:20.800 For live documentation, yardoc.org offers online resources where developers can view their documentation, similar to what php.net provides. Borrowing clever ideas from successful documentation resources is a great practice. YARD can be modified to include plugins, with many useful extensions available.
00:15:12.320 Among suggested plugins are Yard-RSpec which can automatically pull RSpec specifications into documentation, Yard-Sinatra for routing documentation, and Yard-Pigments for syntax highlighting of various languages. These tools enhance the documentation experience and support best practices.
00:15:49.760 Returning to the question of improving documentation efforts, my concluding message emphasizes the need for continuous work towards providing better information to users. Incorporating documentation into the development process is essential, and addressing the associated challenges will deliver benefits to users and empower developers.
00:16:50.000 If you find yourself writing or maintaining libraries or frameworks, I encourage you to give serious thought to implementing better documentation practices. And for those not currently contributing, there remains a significant need for improved documentation in the Ruby standard library. If you're interested in participating, I would love to have discussions regarding documentation improvement.
00:17:28.200 You can visit yardoc.org to install the tool or find more information. I may be a bit short on time here, but thank you all for listening. I'm happy to take questions.
00:18:06.160 (Several questions from the audience follow along with responses.) Yes, I understand the importance of clear parsers, and there are Ruby parsers and C parsers available that can support those needs. However, a bit of improvement is always on the agenda to ensure they meet user needs effectively.
00:20:22.880 To address the connection between documentation and code, I explored methods of linking source and documentation. We recognize that there are methods that can assist in implementing this feature, and the key lies in ensuring that if documentation is well-maintained, it can comprehensively cover the needs of both systems.
00:21:55.160 Finally, I appreciate all your questions, and encourage continuous effort to enhance our approach to documentation. The journey of ensuring quality documentation is ongoing, and I thank you once again for your attention.
Edit