A RDoc Maintainer's View on Ruby's Documentation

As someone who genuinely cares about Ruby's developer experience, I've been thinking about Ruby's documentation for a while, especially after I became a maintainer of RDoc.

And I'd like to share my thoughts on the current state of Ruby's documentation and how we can improve it.

Note: The contents of this article are my personal opinions and do not represent the opinions of other RDoc maintainers or the Ruby core team. The actual roadmap of RDoc and related projects will be decided by the teams responsible for them, so please don't use this article as the official roadmap.

Table of Contents

• RDoc: The Tool, The Markup, and docs.ruby-lang.org
  • English Version
  • Japanese Version
• Top 3 Things I Want to Improve
  • 1. Incrementally Improve RDoc's Default Theme
    • Apply Improvements to All Actively Maintained Ruby Versions
  • 2. Move Away from RDoc Markup Language to Markdown
  • 3. Improving Ruby's English Documentation Website
  • Other Improvements I Want to Make
• Final Thoughts

RDoc: The Tool, The Markup, and docs.ruby-lang.org

Before we talk about documentation in the broader sense, let's discuss RDoc first.

When we mention "RDoc," we might refer to two different things:

• RDoc as a markup language to write documentation (example source and its output). You can write it as comments in Ruby and C source code or as a separate file with a .rdoc extension.
• RDoc as a tool (gem) to generate documentation from Ruby or C source code (link), which supports both Markdown and RDoc markup languages.

Ruby's documentation website, docs.ruby-lang.org, is divided into two parts:

• https://docs.ruby-lang.org/en/ - English version
• https://docs.ruby-lang.org/ja/ - Japanese version

English Version

The English version is generated from the Ruby source code using the version of RDoc bundled with it. For example:

• Master is generated from the ruby/ruby master branch, with the ruby/rdoc master branch (since ruby/rdoc is synced to ruby/ruby).
• Ruby 3.3 is generated from the ruby_3_3 branch of ruby/ruby, with the latest ruby/rdoc commit synced to it.
• Ruby 3.2 is generated from the ruby_3_2 branch of ruby/ruby, with the latest ruby/rdoc commit synced to it.

Different Ruby versions not only have different documentation content but could also have different themes since the English version is generated from the Ruby source code with the bundled RDoc version.

Japanese Version

The Japanese version is maintained separately in rurema/doctree, handling both the theme and content independently.

Top 3 Things I Want to Improve

There are many aspects of Ruby's documentation that can be enhanced. To keep it concise, I'll focus on the top three:

1. Incrementally Improve RDoc's Default Theme
2. Move Away from RDoc Markup Language to Markdown
3. Improving Ruby's English Documentation Website

I'll also touch on other improvements without going into detail. If I haven't mentioned something, it doesn't mean it's unimportant—it might just need more thought.

1. Incrementally Improve RDoc's Default Theme

(And therefore, docs.ruby-lang.org/en/master's theme)

A project's official documentation is often the first thing users see, shaping their initial impression. It should be:

• Easy to read
• Easy to navigate
• Aesthetically pleasing

Over the past few months, I've collaborated with community members to gradually enhance RDoc's default theme. Comparing latest with Ruby 3.3, there should be a noticeable difference. However, there's still room for improvement:

• Better navigation features like breadcrumbs
• Enhanced search results
• Improved SEO optimization
• Support for dark mode

Have ideas or suggestions? Please open an issue or a pull request on RDoc's GitHub repository.

Apply Improvements to All Actively Maintained Ruby Versions

Beyond enhancing the theme, we should also upgrade the infrastructure to apply these changes to all actively maintained Ruby versions (issue). This ensures that improvements benefit most users, even those on older Ruby versions.

2. Move Away from RDoc Markup Language to Markdown

In a world where Markdown is the de facto standard, it's time for Ruby to transition from RDoc markup language.

Benefits of Switching to Markdown:

• Ease for developers: No need to learn a new markup language.
• Better compatibility: Markdown files render properly on many platforms (GitHub, GitLab, etc.), whereas .rdoc files often don't (example).
• Editor support: The Language Server Protocol only supports plain text and Markdown, requiring RDoc markup to be translated if tools want to display it.

Challenges:

1. Enhance RDoc's Markdown parser to support the latest Markdown syntax:
   • The current parser is generated via kpeg, making it hard to maintain and update. This also leads to issues like this.
   • Using parser gems like redcarpet isn't feasible since RDoc, as a default gem, can't depend on external libraries. Alternatives include implementing the parser ourselves or vendoring dependencies without affecting Ruby's distribution.
2. Support RDoc directives in Markdown.
3. Provide a conversion tool from RDoc markup to Markdown:
   • Rails has a tool: rdoc-to-md, which we can collaborate with to improve.
   • We need a similar tool for C source code.

The goal is to let users write documentation in Markdown with the same functionality as RDoc, making it easier to write and maintain documentation through the RDoc tool.

3. Improving Ruby's English Documentation Website

Enhancing Ruby's English documentation website involves addressing several key issues across different projects:

• Poor SEO: The official website often doesn't appear prominently (or at all) in search results, making it harder for developers to find the documentation they need.
  • Additionally, we may embrace standards like llms.txt to improve large language models' ability to understand the content and thus improve their understanding of Ruby.
• Unhelpful Front Page: Currently, the front page displays the project's readme, which isn't helpful for most users looking for documentation. Ideally, it should provide a good index of the commonly used documentation.
• Content Selection and Organization: The documentation content should be more curated and better organized to facilitate easier navigation and discovery of information.

Other Improvements I Want to Make

While the top three are crucial, there are additional areas to enhance:

• Display RBS signatures in documentation
• Add server mode to RDoc (PR)
• Improve RDoc's own documentation
• Migrate RDoc's parser to use Prism instead of Ripper (@tompng has made significant progress on this)
• Ensure the content and links on ruby-lang.org/en remain current and valuable

Final Thoughts

These proposed enhancements are essential for modernizing Ruby's documentation system. By transitioning to Markdown, improving SEO, and upgrading the infrastructure to support all actively maintained Ruby versions, we can significantly enhance the accessibility and usability of the documentation.

Achieving these goals will require increased investment and active collaboration from the community. I've dedicated a lot of time to these issues, and I encourage all contributors to participate in these initiatives to ensure that Ruby's documentation remains current and valuable for all users.