Documentation
The New Design of Ruby's Documentation
Edit
#documentation
#ruby-3
#metaprogramming
#irb
#user-experience-ux
#developer-experience-dx
#ruby-standard-library
Summarized using AI

The New Design of Ruby's Documentation

ITOYANAGI Sakura • November 13, 2018 • Los Angeles, CA

In the video titled "The New Design of Ruby's Documentation" presented at RubyConf 2018 by ITOYANAGI Sakura, the speaker, a documentation maintainer and member of the Ruby core team, discusses the advancements in Ruby's documentation design aimed at enhancing the developer experience. The talk emphasizes the necessity of good documentation as exemplified by other programming languages such as Perl and Python, which have robust documentation tools facilitating user engagement.

Key points discussed include:
- Ruby Documentation Improvements: The speaker highlights the recent improvements in Ruby's documentation, focusing on usability and accessibility enhancements. A structured approach to document modules, classes, methods, and attributes is emphasized to ensure clarity.
- Introduction of New Methods: A specific mention is made of the 'missing' method in Ruby, which allows for flexible method definitions and execution.
- New Readline Library: This library provides enhanced user input handling, including line editing and history features, showcasing ease of implementation alongside existing tools like IRB and Pry. A pure Ruby version of the readline library was introduced to aid beginners who might face challenges with installation.
- IRB Enhancements: Improvements to Ruby's Interactive Ruby Shell (IRB) include enhanced autocomplete functionalities and richer help commands, assisting developers in coding more efficiently.
- Iterative Development Process: The speaker addresses challenges faced during the development of these new features, such as input representation for non-Unicode encodings and the integration of special characters, reaffirming a commitment to user satisfaction.

The conclusion emphasizes the collaborative spirit of the Ruby community and encourages contributions to the ongoing documentation improvement project, highlighting that the enhancements aim to revitalize the overall user experience.

Finally, the speaker opens the session for questions, indicating a willingness to engage with the community and receive feedback on the new documentation efforts.

The New Design of Ruby's Documentation
ITOYANAGI Sakura • November 13, 2018 • Los Angeles, CA

RubyConf 2018 - The New Design of Ruby's Documentation by ITOYANAGI Sakura

Unlike many other languages, Ruby doesn't have great design for documentation. Perl has "perldoc" feature and users easily access documents of modules by "perldoc" command. Python has "docstring" feature and users can access it on REPL. Those are each language's design of importance. The features are not just tool, it contains toolchains and eco-systems. Users of these languages benefit from good documentation design, so library authors write good documentation for them.

I'll talk about new Ruby 3's standard documentation design. It pretty improves your development experience.

RubyConf 2018

00:00:15.770 Okay, today I'll talk about the new design of Ruby's documentation. My name is ITOYANAGI Sakura.
00:00:23.880 Hello everyone, I'm a current documentation maintainer and a member of the Ruby core team.
00:00:30.060 I'm so nervous because it's the last session time for all speakers. It's a bit intimidating.
00:00:39.239 I'm a member of the Ruby core team's success committee, which will be convened this Tuesday.
00:00:47.180 RubyConf 2018 is a great opportunity for all speakers, particularly those from the Ruby community.
00:01:02.550 I am working at Space Pirates, developing front-end applications with JavaScript. It's a challenge because I'm not very familiar with JavaScript.
00:01:15.540 In my free time, I enjoy climbing. Last month, I traveled to the jungle in Malaysia.
00:01:23.189 I experienced a bonfire in the jungle and climbed a waterfall that was over 100 meters tall.
00:01:34.729 Before RubyConf 2018, I planned to go rock climbing at Malibu Creek State Park.
00:01:42.119 However, I was unaware of the recent fire in the area, and my Uber driver informed me that the park was closed.
00:02:01.620 I attempted to find another way but discovered that all Uber services were down due to the fire.
00:02:11.290 I tried walking to a bus stop, which was about three or four miles away, but the fire spread quickly.
00:02:20.440 Eventually, I was rescued by a police car. The situation was quite severe.
00:02:26.620 That area is under reconstruction now, so once it is safe, I recommend visiting.
00:02:35.860 Next, I want to talk about my experience as a Ruby committer.
00:02:44.170 I became a Ruby committer last month during a conference interview.
00:02:53.100 Being a committer means you are actively contributing and collaborating within the Ruby community.
00:03:01.750 The Ruby community is grateful for the contributions of its members.
00:03:09.370 I was also inspired by prominent figures in the Ruby community.
00:03:15.550 Their contributions have greatly influenced the development of Ruby and its documentation.
00:03:27.130 I'm particularly excited about improvements in Ruby's documentation.
00:03:32.800 I'd like to talk about an important feature of Ruby documentation and the new design.
00:03:46.390 The number of Ruby committers has grown, and it's crucial for the community to work collaboratively.
00:03:56.930 The Ruby core team holds regular meetings to discuss progress.
00:04:01.630 I hope to see more committers join the Ruby community and contribute to its growth.
00:04:09.370 The Ruby documentation improvement project started recently, and I encourage everyone to participate.
00:04:15.550 Now, let's dive into the specifics of the new documentation design.
00:04:27.130 Ruby's documentation aims to provide a seamless development experience.
00:04:34.180 We have introduced features that enhance usability and accessibility.
00:04:40.610 These enhancements include updates to the namespace organization and detailed explanations.
00:04:49.200 The documentation will cover modules, classes, methods, and attributes.
00:04:57.280 An example of this is the Ruby class, which serves as a perfect case study for better documentation.
00:05:05.370 With each method, we want to ensure clarity and proper documentation practices.
00:05:12.680 We've also added documentation for several new methods.
00:05:18.120 One notable feature we introduce is the method 'missing' in Ruby.
00:05:24.800 This feature returns specific values depending on the method calls.
00:05:30.580 The 'missing' method provides flexibility in how methods are defined and executed.
00:05:38.270 A notable contributor to this feature is Aaron Patterson, who provided impactful methods.
00:05:45.680 The documentation aims to encapsulate these functionalities in an understandable manner.
00:05:54.070 I'm excited to discuss these enhancements further in the documentation.
00:06:00.300 Let's take a look at our next topic.
00:06:02.290 Now I'll transition to talking about the new readline library in Ruby.
00:06:12.140 This new library provides an improved interface for handling user input.
00:06:22.020 Using this library, developers can expect a smoother experience with input handling.
00:06:30.120 The readline library allows for line editing and history functionality.
00:06:41.880 It consists of predefined functions to facilitate these interactions.
00:06:49.960 For example, you can delete characters and access past inputs effortlessly.
00:06:58.450 I will provide a brief demonstration of how this library works.
00:07:07.250 Note how easy it is to implement and utilize this library in your Ruby applications.
00:07:16.040 Most developers already use libraries like IRB and Pry, which utilize readline.
00:07:24.230 This integration enhances the overall development experience for Ruby users.
00:07:34.290 Furthermore, the readline library is widely recognized among developers.
00:07:44.370 However, it’s essential to ensure the right installation for a seamless experience.
00:07:51.450 Users should ensure that the readline library is properly set up before leveraging it.
00:08:00.850 Keeping up with installation steps can prevent possible frustration and errors.
00:08:11.440 If Ruby lacks the readline library, it can create challenges for beginners.
00:08:20.820 To mitigate this, we decided to implement a pure Ruby version of the readline library.
00:08:27.790 This version will better accommodate those without the original readline library.
00:08:37.390 We've made sure Ruby 2.7 uses this readline library as its default.
00:08:45.820 The new readline library supports input and line editing for enhanced usability.
00:08:54.030 We utilize POSIX functions for system calls within Unix-like operating systems.
00:09:00.130 Various key bindings make using the library effective and user-friendly.
00:09:09.550 However, there are many diverse bindings that can be complex to implement.
00:09:17.250 As a developer using readline, I wanted to ensure that the implementation was robust.
00:09:25.280 Several challenges arose during development, but perseverance led us to success.
00:09:33.510 We've encountered issues with non-Unicode encodings, which we are actively working to fix.
00:09:42.680 Specifically, capturing and processing user input with various encodings proved difficult.
00:09:51.140 Additionally, combining certain characters led to formatting issues in user input.
00:09:58.960 We also had to address problems with input representation for emojis and special characters.
00:10:05.740 Now let's explore how we can effectively handle these challenges.
00:10:13.120 The implementation process has been iterative, focusing on core functionality.
00:10:19.380 We are committed to refining the platform for user satisfaction and reliability.
00:10:27.780 Ultimately, all adjustments aim to foster better coding experiences on Ruby.
00:10:36.000 Next, I'll address the advancements in the IRB, Ruby’s interactive shell.
00:10:45.560 IRB serves as a crucial tool for developers testing and sharing Ruby code.
00:10:54.660 With the latest updates, users are greeted with enhanced features for documentation.
00:11:02.530 The autocomplete functionalities in IRB have been improved significantly.
00:11:09.050 Now, pressing the tab key provides context-sensitive completions.
00:11:16.890 I will showcase how this integration simplifies the coding process.
00:11:26.710 This is a major step forwards as it allows for faster development times.
00:11:36.750 When commands are incomplete, it gives detailed suggestions for completion.
00:11:46.920 Furthermore, IRB's outputs are documented and easily accessible to users.
00:11:55.250 This will eliminate unnecessary confusion and boost interaction efficiency.
00:12:03.220 Now, let’s move on to the features that were recently highlighted.
00:12:09.800 We've enhanced help commands, and they now provide richer, more informative content.
00:12:18.070 Additionally, you’ll find that the commands are better structured for querying.
00:12:26.640 This results in a more engaging coding experience overall.
00:12:35.970 In conclusion, these improvements are aimed at optimizing the user experience.
00:12:44.510 Developers can expect a revitalizing journey while working with Ruby's tools.
00:12:54.790 At this point, we're making great strides in the design and usability.
00:13:02.840 I would like to thank everyone for their ongoing support and enthusiasm!
00:13:10.850 We look forward to seeing you all as we continue to enhance Ruby's documentation.
00:13:20.140 Thank you for your attention! Now, I'll open the floor for questions.
00:13:29.380 I’m happy to take any inquiries or discussions.
00:13:38.030 What questions do you have regarding the new design?
00:13:44.570 Your feedback is critical as we continue to refine our documentation.
00:13:54.020 I appreciate your contributions and engagement with Ruby's evolving ecosystem.
00:14:03.140 Thank you all for your commitment to improving Ruby—let's keep building!
IS
ITOYANAGI Sakura
7 talks
Explore all talks recorded at RubyConf 2018
+82