00:00:00
I think for us it's time to introduce Victor Shepelev, and he's going to talk about the documentation of Ruby itself.
00:00:06
The word 'struggle' in there—well, that doesn't sound good. Anyway, he's a Ukrainian developer—sorry, he calls himself a programmer and poet.
00:00:17
So, he's a programmer and poet with twelve years of programming experience and fifteen years of Ruby programming. He currently works at Verbit.ai, and he also mentors students for the Google Summer of Code.
00:00:33
As a mentor, he has worked on other projects and he is a developer of open source software. Victor, hi! Is that twelve years of experience as a poet and fifteen years developing Ruby?
00:00:51
It's twelve years of programming; I started with C++ before moving to Ruby. And as a poet, it's probably more like thirty-seven years because I'm thirty-seven years old.
00:01:18
Okay, well, I’d like to start with your presentation. Tell us about the struggle for documentation of Ruby itself.
00:01:30
Okay, let's start. I'm here to tell you about the documentation of Ruby itself, as was already mentioned, but I'll reiterate because some of it is important. I have been developing in Ruby for a really long time, and I am in love with Ruby. I want it to remain my main programming language for the coming years.
00:01:55
I have also been mentoring students in Ruby for the last five years, and that's when I started to notice that our documentation could be improved.
00:02:13
You might recognize me as the guy who invented the Kernel Zen method, which split the community, along with some other contributions to the latest versions of Ruby.
00:02:36
I have also added a lot of documentation in recent versions and I maintain the Ruby reference site, which I will talk about through the course of this talk. I was even recognized for this effort by the Fukuoka Ruby Award, which I am quite proud of.
00:02:58
So, let’s ask ourselves this question: How is our documentation? I mean not just the tutorial blog posts or books, which we already know are quite good. There are many talented authors and helpful people on the internet.
00:03:18
But regarding the base language documentation—when I urge you to consider this, I encourage you to think about some random sample questions that students often ask.
00:03:49
Trying to answer these questions often reveals that even some basic questions about Ruby are hard to find in our documentation.
00:04:02
For example, if you go into the question of file reading, which is prevalent in every tutorial, you might not find a clear meta description because it's actually 'IO.read', which 'File' is inherited from.
00:04:26
For novices, this can be a struggle point, and there are many other concepts like 'What are blocks?', 'Where can I find documentation for them in the base language?' and 'What are our documentation conventions?'
00:04:45
These concepts and many good features of our standard library are not easy to find.
00:05:06
When attempting to find answers to some basic questions, we might stumble upon a section of the official Ruby site, which links to some good and well-loved materials like the Ruby Monk tutorials, but it is not always helpful for newcomers.
00:05:35
The reference documentation on the same official site has many links to several helpful resources, but it can be confusing for them.
00:05:59
For example, if you navigate to the official Ruby documentation, you will see a link to documentation that looks like everything is just listed in alphabetical order rather than having a structured table of contents.
00:06:24
If you begin learning Ruby from this, you'll probably feel confused.
00:06:38
We recognize that many users start with tutorials or books, but for experienced programmers returning to the documentation, the structure is not always helpful.
00:07:06
Additionally, the official documentation contains all the classes from core libraries and standard collections, but their organization appears haphazard and is alphabetical.
00:07:29
This can cause frustration as newcomers search for the essential information they need.
00:07:53
We have several different renderings of the core documentation, such as ruby.org and others, which compete in Google search results. Some are rendered better, while others appear more modern.
00:08:18
However, none of them provide a fully comprehensive reference experience.
00:08:42
Another significant issue in our documentation, especially when mentoring students or assisting less experienced colleagues, is the sparse documentation for some core language features.
00:09:03
Of course, this can be understandable since the language evolves constantly. Many people work on it, and changes happen frequently.
00:09:21
A prime example of sparse documentation relates to 'pros' found in documentation for versions 2.5 and onwards. Since then, the documentation has improved, but the pros documentation became overloaded, which can overwhelm newcomers.
00:09:58
In summary, the depth of our current language documentation is highly variable.
00:10:07
Some classes contain no documentation, while others offer excessive detail.
00:10:20
Furthermore, some classes are difficult to discover due to the mixture of libraries in the standard library documentation.
00:10:46
This documentation includes a jumble of libraries that are convenient for daily programming, along with outdated information.
00:11:06
These inconsistencies also lead to contradictions within the documentation—if one tries to navigate the file and temp file documentation, it can be confusing.
00:11:29
Moreover, one of the most important issues is the actuality of our documentation. I have been working on an annotated list of all changes in recent Ruby versions starting from version 2.6...
00:11:56
Currently, I am documenting changes in each version, and what I've noticed is that several things listed in change logs are not reflected in the existing documentation.
00:12:23
While some improvements have been made, many issues remain unresolved.
00:12:40
When I started learning Ruby almost twenty years ago, the go-to resource was the book 'Programming Ruby' by the Pragmatic Programmers, which was an excellent documentation tool.
00:13:03
Unfortunately, this book has not been updated for newer language versions and lacks updates on significant changes.
00:13:21
Now there are various resources that cover different aspects of Ruby, but we seem to lack a good overall reference.
00:13:39
We can observe our competitors—if you visit Python’s documentation site, you'll find a helpful list of up-to-date links to documents and structured references covering all language aspects.
00:14:01
If you explore Rust's, Elixir's, or PHP's documentation, you see the same commitment to clarity and usability. Unfortunately, Ruby lacks this kind of structured documentation.
00:14:17
What we really need is a comprehensive reference that covers the complete picture, allowing users to see how everything connects.
00:14:39
Currently, we do not have an official reference for the Ruby language or the library. Deeper topics, such as embedding Ruby in other programs or how to write extensions, are also missing.
00:15:00
However, we do have a great community; many people are supportive on platforms like Reddit and Twitter.
00:15:21
Speaking from my experience, when I wrote to the Ruby Talk mailing list with what I thought was a silly question, I even received a response from Matt himself. This shows the supportive nature of our community.
00:15:41
The existence of a reference is essential as it shapes how a language is perceived. It helps newcomers access a wealth of structured information rather than relying on scattered blog posts and stack overflow responses.
00:16:01
It also aids experienced programmers transitioning from other languages who are looking to understand Ruby's nuances.
00:16:20
In some cases, this issue extends beyond newcomers to seasoned developers who are establishing their understanding.
00:16:39
The vast, sometimes confusing information can obscure how features interrelate, leading to gaps in knowledge.
00:16:57
Many people coming to Ruby do so to work with Rails, which has fantastic documentation. However, this can create a disconnect where the community knows Rails better than Ruby itself.
00:17:14
Noticing these gaps is vital for productivity, especially when individuals from other programming backgrounds come to Ruby and look for resources.
00:17:34
These discrepancies in understanding between Rails and Ruby can lead to misunderstandings about Ruby itself, as Rails is often perceived as the essence of Ruby.
00:17:54
While my concerns stem from Ruby's documentation issues, the perception of Ruby as a complex programming language serves to alienate potential users.
00:18:14
Ruby is consistent in its design, with a small core of well-implemented features that provide expressiveness, but this diminishes when users study it without a solid reference.
00:18:36
So yes, there's certainly room for improvement in documentation.
00:18:56
However, I believe we can make it better. We are a passionate community that wants our language to thrive. We are capable and ready to explain things and to understand where challenges lie.
00:19:15
It’s important that we encourage everyone to participate in this endeavor. It's not just on the seasoned developers but also on new contributors.
00:19:32
Writing blog posts helps, but consider creating small documentation sites for easy reference.
00:19:51
Expanding existing Ruby documentation is crucial. A simple pull request can enhance clarity and assist countless users.
00:20:08
A collaborative culture of encouraging more accessible references will greatly facilitate newcomers.
00:20:29
The last notable challenge is creating a balance in documentation style; inconsistencies can confuse users.
00:20:48
I have initiated my own project called Ruby Reference, which aims to gather existing resources and establish a clearer document structure.
00:21:06
While it's a step in the right direction, it’s helpful to involve the community as a whole in this task.
00:21:29
There are significant efforts currently underway, and I commend everyone actively contributing to documentation.
00:21:50
For instance, individuals like the maintainer of rubydoc.org and the new Ruby API reference site make it easier to access modern documentation.
00:22:08
There are numerous people across the community who are committed to improving Ruby's documentation.
00:22:29
Finally, I want to emphasize the importance of advocating for better documentation quality—a collective effort is essential.
00:22:51
I call upon all of you here—please participate! Your perspective as newer users brings invaluable insights into where documentation may lack clarity.
00:23:15
A ticket on an official Ruby bug tracker highlighting what needs clarity can do wonders for the community.
00:23:36
In closing, let’s make Ruby documentation better, ensuring that we foster understanding and excitement in this language.
00:23:58
Thank you very much.
00:24:10
I think you made fantastic points, Victor. Clearly, you have a talent for communicating complex ideas.
00:24:29
And as you were saying, enhancing the documentation impacts everyone positively, especially those new to programming.
00:25:00
Your talk was enlightening, and I hope everyone feels inspired to improve Ruby documentation.
00:25:32
Thank you once again, Victor.
