我自己沒有資工背景（大學念公共行政），也沒有出國留學過，一路上是受到很多人的幫助才能走到這裡。作為台灣人想透過開源專案建立職涯，真的不是件容易的事。語言、時區、文化差異都是挑戰。但如果我可以走到這裡，或許也能給其他人一些經驗參考。

這篇文章整理了我這幾年的心得，大部分內容來自我和 Ruby Taiwan 社群的一場 AMA，所以內容會比較鬆散一點。

我的背景

2013 年在大學開始自學寫程式，畢業前就陸續在 flyingV、愛料理、貝殼放大實習跟工作。2017 年從台灣找到一份英國公司的遠端工作，做了四年後搬到英國，半年後加入 Shopify 的 Ruby Developer Experience team，一直到現在。

我的工作內容是改善 Ruby 開發者的體驗 —— 開發維護 Ruby LSP、type checker、debugger、還有各種開發工具。

認識開源社群是在愛料理工作的時候。那時開始用 Ruby on Rails，偶爾會去看 gem 的 source code，意識到自己「好像可以貢獻些什麼」，並在當時 CTO Richard 的鼓勵下開始嘗試做些小的貢獻。

而我比較積極參與 Ruby 社群，則是在 2015 年夏天去了新加坡的 RedDot RubyConf，年底又去了第一次的 RubyKaigi 之後。那時在會場看到差不多年紀的工程師說「我維護這個專案」、「我是 Rails 前 100 個貢獻者」，覺得靠寫程式跟開源專案就能對一個社群有影響力，是很酷的事情。

給想開始認真貢獻的人

幾個實際的建議：

選跟工作相關的專案

這代表你已經知道一部分的 context，不用額外花時間建環境。你甚至可以跟公司討論：讓我花一部分上班時間修這個 issue、upstream 到原本的 gem，會比在專案裡加 patch 更好維護。這件事情我即便到現在在 Shopify 都還很常做。

用 AI 幫助你了解 codebase

去年我開始貢獻 ZJIT，一個用 Rust 寫的 JIT compiler。我之前沒做過任何 JIT compiler、沒貢獻過 Ruby 本身、也沒寫過 Rust。 但靠 AI 幫我快速了解 codebase，大幅降低了語言不熟的門檻，讓我能夠專心學習 JIT 相關的知識跟快速跟上開發。

以前這些全部都要自己慢慢摸索，現在用 AI 可能半天到一天就能知道專案的架構、每個部分在做什麼、測試怎麼寫。

從小地方開始貢獻

如果你找了一個專案但不知道從何開始貢獻，這些會是我的建議：

• 改善測試 —— 例如把重複的 setup 抽出來變成 helper method、重寫難懂的測試等等。測試不會影響使用者，maintainer 更容易 merge。
• 找 TODO comment —— 那些放在那邊很久沒人修的東西。
• 消掉 deprecation warning —— 讓畫面看起來乾淨。

這些小事可以讓你增加對 codebase 的了解，同時建立和 maintainer 之間的信任。

現在有了 AI，偵測這些東西變得容易許多。但是切記自己要驗證、review 過再開 PR。如果維護者覺得你發 AI slop，沒人會想認真 review 跟接受你的 PR。

反過來說，有些東西不太適合拿來當第一次的貢獻：

• 變更 dependency —— 一個專案的 dependency 對開發流程跟使用者都有很大的影響，在不熟悉專案前很容易做出不正確的判斷。
• 變更 linting rules —— 每個團隊有自己的開發文化跟偏好，在不熟前不適合介入。

投資 40 個小時在同一個專案上

大概要花到這個時間，你才能真的說你了解這個專案的一部分，包括開發慣例跟流程。走到這個階段，你貢獻的東西會比較能放上履歷，學到的東西也會比較多。

在你貢獻滿一定時數之後，你很可能會發現：

• 相關的專案好像也有類似的問題，可以順便貢獻
• 相關經驗可以寫成一篇文章
• 維護者在找人幫忙維護，你是少數有足夠貢獻量的人選

（40 小時是個人經驗，實際數字會因人而異）

用公開的工具問問題

用 GitHub issue 而不是 email。你問的問題別人可能也會有，公開之後 maintainer 只要回答一次，之後有人再問就指向這個 issue。

不用擔心問問題會麻煩 maintainer。任何人變成 maintainer 都知道回答問題是維護的一部分。只要有人願意參與，我們都看得到，這些都是好的。

不過有時候你問了問題或開了 PR，maintainer 很久沒回，不代表他沒看到 —— 很多時候是他知道這很重要，但需要花時間思考，或是有更緊急的事要先處理。大部分專案等一兩週才有回覆是很正常的，避免過兩三天就留言追問。

短期專注，長期開放

如果你已經有貢獻經驗，而且考慮把開源專案變成你職涯的重心，我會建議：短期（1-2 年）專注一個領域，但長期保持開放，不要死守單一專案。

舉例來說，過去五年我的貢獻路徑是這樣：debug.gem → Ruby LSP → IRB → RDoc → ZJIT。

一開始貢獻 debug.gem 時，花了超過 200 個 PR 成為第二大 contributor。後來因為工作接觸 Ruby LSP，開始了解 LSP server 跟編輯器。接觸 IRB 後又慢慢從成為 maintainer 到變成第一貢獻者。接著是 RDoc，從 2024 年到現在已經兩度幫它換皮，現在則是重寫並增加它的功能。去年中也密集貢獻了 Ruby 的下一代 JIT compiler（ZJIT），學習了不少程式語言底層的實作跟優化。

如果剛要開始貢獻的話，目標最好是平常會用的東西，這樣學習的成本會小很多。

像我 2019 年貢獻最多 Rails，那時候還在做 Rails 開發，可以在自己公司的專案裡實驗 patch，確認可以動再送上去。2022 年加入 Shopify 做 Ruby DX 之後，碰不到 Rails 了，自然就轉向貢獻 Ruby 本身和周邊工具。

但過一段時間上手後，也應該試著拓展貢獻的領域。原因有兩個：

第一，如果你的專長太局限，會很難把它跟公司變動的需求做連結，導致你能發揮的場域受限。第二，當你有意識地拓展接觸的專案類型，會幫助你從不同的專案汲取靈感。像我是從 debugger 到 LSP server 再到 REPL，慢慢地從一個單一工具的專家，變成大部分開發者工具都是我熟悉的領域，甚至進一步整合不同的專案。

最近的例子是 AI 開發工具成為主流後，我也開始嘗試開發相關的工具，例如 cctop、ruby-skills、rubydex 的 MCP server 等等。

光寫 code 不夠

這點很重要：光寫 code 其實不夠，還需要透過部落格、活動、演講讓別人看見你的貢獻。

開源社群裡很重要的一點是信任。你要變成 maintainer、要得到別人的幫助，這些全部都是基於「我信任你這個人」。如果你平常不講話，沒有人知道你是誰，信任就會來得比較慢。

我做了幾件事讓社群認識我：

去 Conference

從 2015 年開始，除了疫情那三年，我每年都去 RubyKaigi。不管公司有沒有贊助，我都會自己買機票。每一天都一定會去一個活動 —— 不管是喝酒的還是 coding party。

RubyKaigi 的 coding party 很多 Ruby 和 Rails maintainer 都會去。你可以坐在他們旁邊，跟他們一起討論、一起修 PR。我之前就有一次在 coding party 開了好幾個 Rails PR，maintainer 直接就 merge 了，因為就坐在旁邊嘛。

我第一年去 RubyKaigi 不敢跟 Matz（Ruby 發明者）講話，第二年開始跟他打招呼，之後每年都去 say hi。在 RubyKaigi 見一次、在台灣 RubyConfTW 再見一次、在新加坡 RedDot RubyConf 再見一次。慢慢地他也認識我了。

我當初會加入 Shopify，其實也是因為 2021 年在線上的 Euruko 認識了現在的同事，幾個月後找工作時靠他內推才拿到面試機會。

寫部落格

你可以寫公司裡做了什麼、用了什麼 gem、今天貢獻了什麼 PR。不用很長，分享你學到的東西就好。我建議用英文，因為理論上越多人看到越好。你都已經花時間了，用 AI 把它翻譯成英文，讓更多人看到。

寫完之後分享到 Reddit、X 或其他地方，慢慢就會有人知道你的 ID、知道你是誰。

上台演講

這可能是壓力最大的，但也是最有效的。

我第一次上台演講就是在 RubyKaigi 講我自己做的很爛的程式語言。多虧了慕凡跟龍哥給我很多幫助和鼓勵。講了第一次之後，就慢慢知道自己做得到這件事。

當公司在看履歷的時候，他們可能沒辦法點進去看你 5 個 Rails PR 的討論串。但如果你跟他說你在 RubyConf Taiwan 講過 30 分鐘，他可以快速滑一下你的影片、點過你的 slides。用這個方式來證明你的能力很有效。至少我會對你的溝通能力有一定的信心，因為你敢站上台分享你學的東西。

不要因為英文退縮

很多人問我：英文不好怎麼辦？

我英文一開始也不好。為了貢獻開源專案、參與社群、到國外找工作，額外花了很多時間練英文。我現在還找得到我第一個 PR，描述裡兩句話就有三個文法錯誤。

但那完全沒關係。

社群裡很多 maintainer 來自西班牙、法國、非洲，英文也都不是他們的母語，寫英文的時候常常會有文法錯誤。台灣人並沒有比較劣勢。

比較劣勢的是：因為覺得自己英文不好，所以就不敢講話。

英文不好不是問題，但不要因為英文不好讓你不敢講話、不敢上台、不敢在 issue 上面回覆訊息。如果真的因為英文不好而不敢開口，那就投資時間改善它 —— 不是為了達到別人的標準，而是為了說服你自己：我英文夠好，我敢講話。

台灣的教育讓我們讀寫應該都沒問題，其實只差嘴巴講出來的自信心跟流暢度。每天唸英文新聞、讓嘴巴肌肉習慣那個發音，三個月你就會發現差很多。

這需要很大的前期投入

我每年大概花 500 到 1000 個小時的個人時間在各種開源專案上面。

這個職涯對我來說很有用，但我其實不推薦給大部分的人。因為它的背後是這麼大量的時間投入，而且不保證有回報。你可能花一兩百個小時刷 LeetCode，就能拿到同等級的 offer。

我一開始貢獻開源專案，其實是想要展現我寫程式的能力。我是非本科出身、沒上過任何課、完全沒有相關背景。我不想用 LeetCode、不想刷演算法（我刷演算法超爛）。我想用公開的成果，讓別人看我花 8 個小時寫的 code，而不是用我 30 分鐘壓力下寫出來的 LeetCode 來判斷我的能力。

後來我的職涯也確實都是這樣。從第一份實習之後，我幾乎都不用投履歷，都是靠別人的 refer。即便到 Shopify，也是別人介紹、用開源專案來面試。

但如果你對這件事情沒有熱忱，就不值得花這個時間。最好是因為真的喜歡才做。

最後

用開源專案建立職涯，對我來說是一條很值得的路。但它需要很大的前期投入、需要你願意曝光自己、需要跨過語言和文化的障礙。而且不保證有回報。

如果你正在想這條路適不適合自己，希望這篇文章能提供一些參考。

Eventually you add something like Use chruby 4.0.0 to run Ruby commands in either the project or your user-level CLAUDE.md.

While this is frustrating, I don’t blame Claude. Ruby has at least seven version managers - rbenv, chruby, rvm, asdf, mise, rv, shadowenv - and Claude doesn’t know which one you’re using.

This is an example of a bigger question: how can a community teach AI to handle its ecosystem’s quirks? Or how does it know about areas that are still rapidly developing, like the typing and tooling scene in Ruby?

So I built ruby-skills to solve the version manager problem and experiment with community-maintained guardrails for Claude Code.

What ruby-skills provides

Think of it as a starter pack for Ruby development in Claude Code - helping Claude understand your Ruby environment and find the right resources:

• Know how to run Ruby correctly - detects your version manager and activates the right Ruby version
• Know where to look for resources - points Claude to authoritative documentation sources
• Connect with the language server - integrates Ruby LSP for code intelligence

The project provides two plugins:

ruby-skills plugin

Contains Ruby-specific skills:

ruby-version-manager: Detects your version manager and which Ruby version your project requires. Instead of running bundle install and failing, Claude runs:

<version manager activation command> && bundle install

The activation command is prepended because Claude Code runs each command in a fresh shell - environment changes don’t persist between commands.

Ruby LSP’s VS Code extension solves the same problem for editors - it activates the correct Ruby so the language server and other extensions can invoke Ruby commands correctly. This skill does the same for Claude Code.

When multiple version managers are detected, Claude asks which one you prefer:

ruby-resource-map: Provides links to authoritative Ruby documentation (docs.ruby-lang.org) and advises avoiding known outdated sources like apidock.com (an unmaintained Ruby documentation site that often shows up in the top search results).

It also briefly explains the current situation in areas where official guidance is scarce or changing rapidly, like the typing ecosystem (Sorbet vs Steep, RBI vs RBS), and links to relevant projects. Without this, Claude might provide outdated suggestions based on old training data and bad references.

ruby-lsp plugin

Integrates Ruby LSP for code intelligence - hover documentation, go-to-definition, diagnostics. It uses the version manager skill to activate the correct Ruby before running the LSP server. (Note: LSP integration in Claude Code is new and currently less feature-rich than MCP integration.)

A quick note on Claude Code plugins

Here’s some Claude Code terminology (see official documentation for details):

• Marketplace: A repository that hosts multiple plugins. Communities can create their own marketplace to distribute related plugins together.
• Plugins: Extend Claude Code’s capabilities. A plugin can provide LSP integration for code intelligence, MCP integration for custom tools, or skills that teach Claude domain-specific knowledge.
• Skills: Instructions that guide Claude’s behavior for specific tasks.

Anthropic maintains an official plugins repository with plugins for popular tools like Playwright and Sentry, as well as LSP integrations for many languages.

Why Claude Code specific

In the longer term, I want to make this project vendor-agnostic - it should work with Claude Code, Codex, OpenCode, etc. But I started with Claude Code because:

• I use it daily, at work and personally, so I can test what I build in real workflows.
• Claude Code has the most mature skill and plugin system and community. Building from here is easier.

What I think will happen with language-specific skills

As AI coding tools mature, I think language-specific plugins will naturally emerge from each community rather than being centralized in official or popular marketplaces. It makes more sense for people close to the tools to build and maintain these bridges - I’d expect something like ruby/agent-skills to eventually exist under the Ruby organization.

Generic AI tools handle syntax and common patterns well. But every language has ecosystem quirks that require community knowledge - the version manager fragmentation I described above is one Ruby-specific example that Rust or Go developers don’t face the same way. Contributing Ruby-specific logic to a centralized repository creates a mismatch: maintainers unfamiliar with Ruby would have to review and maintain code for tools they don’t use.

Skills also build on skills. Once Claude knows how to activate the right Ruby version, other Ruby skills become possible. A future RuboCop skill that configures project linting rules would need to invoke Ruby correctly first. The version manager skill becomes a foundation.

This is why instead of adding a ruby-lsp plugin to the official plugins repo, I decided to host it alongside the skill.

Try it out

# Add the marketplace
claude plugin marketplace add st0012/ruby-skills

# Install the plugins (format: plugin-name@marketplace-name)
claude plugin install ruby-skills@ruby-skills
claude plugin install ruby-lsp@ruby-skills

See the README for detailed documentation.

The long-term goal is to upstream these plugins to the ruby/ organization - the experiment is whether community-maintained skills are worth the effort. Feedback, issues, and contributions are welcome on GitHub.

This year I want to focus on the writing experience—and how documentation might need to evolve for the AI era.

Moving toward Markdown

RDoc markup has served Ruby well, but Markdown has become the industry standard. Most developers already know it. RDoc markup, being Ruby-specific, creates unnecessary friction for contributors.

I’ve been working on improving RDoc’s Markdown support to reach feature parity with GitHub Flavored Markdown. Although RDoc has supported Markdown for many years, it was buggy and lacked documentation. So starting this year, I’ve been working on fixing those issues. Some recent changes:

• GitHub-style heading anchors: Headings now generate lowercase, hyphenated anchors (like #my-heading instead of #label-My+Heading). Markdown links like [link](#my-heading) now work as expected. Legacy anchors are preserved as hidden elements so existing links don’t break.
• Strikethrough: ~~text~~ now renders properly in Markdown files.
• Backticks in RDoc markup: Users can now use backticks (`) in addition to + for inline code. This is a common mistake in Ruby core documentation contributions—rather than correcting people, we should just support what they naturally write.
• Better code block handling: Fixed issues where non-Ruby code blocks were incorrectly getting Ruby syntax highlighting.

I’ve also rebuilt RDoc’s markup documentation to better explain what’s supported in each format.

The above changes have been shipped in RDoc v7.1.0.

The long-term goal is to make Markdown the default for Ruby documentation and help existing RDoc markup projects migrate to Markdown.

RBS integration

Type information is becoming more valuable—both for developers and for AI tools that consume documentation. I want RDoc to support displaying RBS signatures alongside method documentation.

This means integrating inline and external RBS signatures into both HTML and RI output, with dedicated documentation section for type definitions (e.g. type aliases, generic types, etc.).

Documentation for AI

This is more exploratory, but I think documentation tools need to consider how AI agents consume documentation.

One direction is generating LLM-friendly output formats. GitBook’s approach with llms.txt and markdown-only pages is interesting. Markdown is more token-efficient than HTML, and having a single-file documentation dump could be useful for context windows.

Another direction is agent skills that help write documentation. I’ve been thinking about what this could look like for RDoc:

• Setting up RDoc for a project, from documentation generation to deployment on GitHub pages
• Writing documentation using RDoc features and directives

Not directly related to RDoc, but I also would like to explore general Ruby skills, like:

• Navigating common Ruby environment issues (version managers, bundler, etc.)
• Using ri to look up existing Ruby documentation for more effective Ruby programming

What’s next

The Markdown improvements and documentation overhaul are ongoing. RBS integration is next on the list, targeting RubyKaigi. The AI-related work is something I’ll explore throughout the year as I continue to use these tools myself.

If you’re generating documentation with RDoc and run into issues with any of these newer features, please open an issue.

It mostly worked — Claude debugged the issue, I reviewed the changes, and pushed a fix, which triggers the deployment, all from my phone while I was out.

That said, I ran into a few things that made the experience less smooth than I expected. If you’re a Ruby developer thinking about trying this, here’s what to know:

The cloud environment won’t match your local setup. Code sessions run in a standardized Anthropic-managed VM with rbenv and Ruby 3.3.6 as the default. My site uses chruby and Ruby 4.0.0 and I wrote my CLAUDE.md based on it. In the cloud environment Claude tried and failed to follow these, then just gave up on building my Jekyll site to actually test the fix.

I needed to push it to sort out the environment issue, commit detailed instructions for that into CLAUDE.md, and verify the fixes after rebuilding the site. The cloud environment specific instructions are necessary for things to work consistently across multiple Code sessions.

There’s no editor view. You can’t easily see code changes as you go — there’s no editor pane. You either check individual tool outputs, ask Claude to summarize changes, or open a PR to see the diff there.

Sessions seem tied to a single PR. After my first PR was merged, I tried adding follow-up changes in the same session. Neither pushing to the rebased branch nor creating a new branch made Claude realize it needed to create a different PR — the UI kept showing the old, merged one. I’m not sure if this is a bug or intended behavior.

I’m genuinely excited that I can now address website issues and publish content from my phone. The experience was good enough that I’ll probably use it again.

I’m less excited about hearing “You can fix this on your phone” in the future.

I want to use this post to document my opinions on AI coding tools and OSS maintenance at this specific point.

With the rate AI models and coding tools improve, I’d be curious to see how much of my takes hold or change after 6 months/a year.

About me

I’m a Ruby committer. I also maintain Ruby’s RDoc, IRB, and Reline libraries.

I don’t see myself as an AI expert, perhaps not even a power user. I use AI tools regularly at work and for OSS development, but haven’t explored many advanced features, such as custom skills. My primary setup is Claude Code with Opus 4.5, so my takes are largely shaped by that.

I’ve used AI to assist my contributions to ZJIT and the creation of Ruby’s new documentation theme. Without AI, I wouldn’t have attempted these—or not to the same extent, due to the upfront cost.

More developers will contribute to OSS using AI tools

I think a main reason is that they see it works well in their work/personal projects. Laziness and malicious attempts could also be behind some people’s contributions, but I want to believe that the majority genuinely believe AI is helping them contribute.

AI coding skills vary even more than traditional coding skills

Just like every developer’s coding skill can vary, sometimes a lot, our AI coding skills and perceptions on coding with AI can vary a lot too. I’d argue that as of now, the difference could be even bigger than traditional coding skill differences.

We have more variables now:

• The models people have access to (due to budget limits, company policies, regions, etc.)
• Usage limits
• The interfaces they use (CLI, IDE integration, chat)
• What projects they use those tools on daily
• The person’s moral compass
• …and many others

(I don’t want to get too deep into these variables here.)

AI is a multiplier, not a leveler

AI amplifies existing developer habits, good or bad. If you lack certain good traits in software development—curiosity, willingness to dig into root causes, knowing when to ask for help…etc.—AI won’t fill that hole. It’ll just help you produce more of whatever you were already producing.

The maintainer’s dilemma

As an OSS maintainer, I don’t get to control what tools people use to “help” them contribute to the project, or how they use it.

I’ve seen more developers feel “enabled” by AI tools to start contributing to OSS projects. In other words, those devs would not have contributed without these tools. I’m one of those devs in terms of contributing to ZJIT, as I’ve detailed in a previous post.

But this also means we’re seeing more low-effort, low-quality contributions.

So what distinguishes good-faith AI-assisted contributions from low-effort ones? I don’t have a good definition that’s worth sharing, but here’s what I look for:

• Did the contributor commit the changes themselves? (indicates they at least did a final review, hopefully)
• Can they answer: what problem they’re solving, and why this specific approach?

The solution exploration doesn’t need to be exhaustive—it’s okay to make mistakes and ask questions. The point is: have good intent and stay engaged with their own work.

AI agents are changing the maintainer-contributor dynamic

Before AI tools, the contribution process involved two parties: maintainers and contributors (it can also involve community discussions, but let’s keep it simple for now). Now there are three: maintainers, contributors, and contributors’ agents.

This creates new communication channels:

• Maintainer → Contributor: CONTRIBUTING.md, PR reviews (unchanged)
• Maintainer → Contributor’s Agent: Agent instruction files like AGENTS.md, CLAUDE.md, etc. (new)
• Contributor → Their Agent: prompts, instructions

Agent instructions talk directly to agents, not necessarily to contributors. A contributor might not read your docs, but their agent is more likely to. This lets maintainers influence how contributors’ tools behave in their repo.

For example, maintainers can ask agents to:

• Care about commit hygiene
• Not commit anything that breaks tests
• Be concise when generating comments, or use a specific format

In the past, these practices were hard to enforce—you could document them, but contributors might not read or follow them. Now that agents are in the loop and tend to follow instructions, maybe this brings some positivity to maintainers too.

But in my opinion, one channel should stay the same: Contributor → Maintainer communication should remain human-to-human. PRs and discussions should come from the contributor, not their agent.

This doesn’t mean you can’t use AI to help draft a PR description—just review it like you would with the code. The expectation is that you’ve reviewed and understood what you’re submitting.

What does this mean to maintainers

Given this new dynamic, I think projects should provide AI-related guidance via agent instruction files. This isn’t about preventing AI slop, as you can’t really stop bad contributions, with or without AI. It’s about empowering good-faith contributors, your fellow maintainers, and their agents to work more effectively with your project.

Yes, it will add more to the maintainer’s plate. But AI can help with that too—if maintainers have access to these tools.

AI companies should sponsor maintainers

Contributors now have access to powerful AI tools. But many maintainers don’t—and without them, maintainers only feel the negatives: more contributions to review, some low-quality, without the means to keep up.

I personally think AI coding tools are the biggest developer productivity boost in recent memory. And the people maintaining our shared infrastructure should have access to them too.

Similar to how CDN and hosting companies sponsor usage credits to OSS projects, I think AI companies can sponsor access to their tools. For example, maintainers of popular OSS projects could get Claude Code Max free of charge.

The exact mechanism could vary—credits, free tiers, partnerships—but providing sponsorship hits multiple birds with one stone:

• It helps projects progress faster
• It allows maintainers to catch up with contributors’ tooling and respond accordingly (e.g., maintain good agent instructions)
• Publicly visible agent instructions (AGENTS.md, skills, etc.) enable sharing real-world agentic coding practices, which helps broader adoption

If these tools help developers ship faster, let’s make sure maintainers have access too.

To contributors

I encourage using AI to contribute to projects I maintain. The expectations I outlined earlier apply here too—review your own work, be able to explain what and why.

If you want to contribute but aren’t familiar with the codebase, use AI to help you learn. Ask it questions and verify the answers by digging into the code yourself. Treat AI as another person who’s also new to the codebase—have discussions together, run experiments together.

To maintainers who haven’t tried AI tools

If you’re still skeptical, I’d echo Armin Ronacher’s advice: give yourself a week to really try it. Not just a quick test—actually use it for tasks you’re already planning to do.

I recommend treating it as a second pair of eyes first. Let it help you with tasks you already understand well, so you can evaluate its output critically.

Once you’re comfortable, create an AI instruction file like AGENTS.md with AI’s help. At the very least, tell AI how to:

• Build your project
• Run tests
• Run linters
• Run end-to-end tests (if applicable)

The latest models should be able to help you generate these with minimal input. If you’re missing any of these instructions in your CONTRIBUTING.md, you can improve it together as well.

With these instructions in place, agents can do a lot with minimal intervention:

• Prototype a few solutions to an issue and summarize the results
• Identify and remove dead code, then run tests to verify
• Execute and test documented code examples

This is where I feel the agents start to increase my productivity significantly.

Long-term optimism

I think in the long run, AI will help the community maintain and improve OSS projects.

RDoc’s new Aliki theme is one example—I wouldn’t have built it without AI. Beyond that, AI has helped me address markdown parsing issues, explore refactoring ideas, and more. It’s made project maintenance a bit more fun, instead of just extra debugging on weekends.

I’d be interested to see if AI tools will help revive unmaintained projects. And whether they’ll help raise a new generation of contributors—or even maintainers.

This post was originally published on September 8, 2025 on Rails at Scale.

Ever since YJIT’s introduction, I’ve felt simultaneously close to and distant from Ruby’s JIT compiler. I know how to enable it in my Ruby programs. I know it makes my Ruby programs run faster by compiling some of them into machine code. But my understanding around YJIT, or JIT compilers in Ruby in general, seems to end here.

A few months ago, my colleague Max Bernstein wrote ZJIT has been merged into Ruby to explain how ZJIT compiles Ruby’s bytecode to HIR, LIR, and then to native code. It sheds some light on how JIT compilers can compile our program, which is why I started to contribute to ZJIT in July. But I still had many questions unanswered before digging into the source code and asking the JIT experts around me (Max, Kokubun, and Alan).

So I want to use this post to answer some questions/mental gaps you might also have about JIT compilers for Ruby:

1. Where does JIT-compiled code actually live?
2. How does Ruby actually execute JIT code?
3. How does Ruby decide what to compile?
4. Why does JIT-compiled code fall back to the interpreter?

While we use ZJIT (Ruby’s experimental next-generation JIT) as our reference, these concepts apply equally to YJIT as well.

Where JIT-Compiled Code Actually Lives

Ruby ISEQs and YARV Bytecode

When Ruby loads your code, it compiles each method into an Instruction Sequence (ISEQ) - a data structure containing YARV (CRuby virtual machine) bytecode instructions.

(If you’re not familiar with YARV instructions or want to learn more, Kevin Newton wrote a great blog series to introduce them)

Let’s start with a simple example:

def foo
  bar
end

def bar
  42
end

Running ruby --dump=insn example.rb shows us the bytecode:

== disasm: #<ISeq:foo@example.rb:1 (1,0)-(3,3)>
0000 putself                                                          (   2)[LiCa]
0001 opt_send_without_block                 <calldata!mid:bar, argc:0, FCALL|VCALL|ARGS_SIMPLE>
0003 leave                                  [Re]

== disasm: #<ISeq:bar@example.rb:5 (5,0)-(7,3)>
0000 putobject                              42                        (   6)[LiCa]
0002 leave                                  [Re]

JIT-Compiled Code Lives on ISEQ Too

I assumed JIT-compiled code would replace bytecode—after all, native code is faster. But Ruby keeps both, for good reason.

Here’s what an ISEQ looks like initially:

ISEQ (foo method)
├── body
│   ├── bytecode: [putself, opt_send_without_block, leave]
│   ├── jit_entry: NULL  // No JIT code yet
│   ├── jit_entry_calls: 0  // Call counter

After the method is called repeatedly and gets JIT-compiled:

ISEQ (foo method)
├── body
│   ├── bytecode: [putself, opt_send_without_block, leave]  // Still here!
│   ├── jit_entry: 0x7f8b2c001000  // Pointer to native machine code
│   ├── jit_entry_calls: 35  // Reached compilation threshold

The jit_entry field is the gateway to native code. When it’s NULL, Ruby interprets bytecode. When it points to compiled code, Ruby can jump directly to machine instructions. But the bytecode never goes away - Ruby needs it for de-optimization, which we will explore a bit later.

The Execution Switch: From Bytecode to Native Code

This is easier than I expected. Since each ISEQ points to its JIT compiled code when it’s available, Ruby simply checks the jit_entry field on every ISEQ it’s going to execute:

When there’s no JIT code (jit_entry is NULL), it continues interpreting. Otherwise, it runs the compiled native code.

How Ruby Decides What to Compile

Ruby doesn’t compile methods randomly or all at once. Instead, methods earn compilation through repeated use. In ZJIT, this happens in two phases:

if (body->jit_entry == NULL && rb_zjit_enabled_p) {
    body->jit_entry_calls++;

    // Phase 1: Profile the method
    if (body->jit_entry_calls == rb_zjit_profile_threshold) {
        rb_zjit_profile_enable(iseq);
    }

    // Phase 2: Compile to native code
    if (body->jit_entry_calls == rb_zjit_call_threshold) {
        rb_zjit_compile_iseq(iseq, false);
        // After this, jit_entry points to machine code
    }
}

As of now, ZJIT’s default profile threshold is 25 and compile threshold is 30 (both may change in the future). So a method’s lifecycle may look like this:

Calls:     0 ─────────── 25 ────────── 30 ─────────────────►
           │              │             │
Mode:      └─ Interpret ──┴── Profile ──┴─ Native Code (JIT compiled)

This is why we need to “warm up” the program before we get the peak performance with JIT.

When JIT Code Gives Up: Understanding De-optimization

JIT code makes assumptions to run fast. When those assumptions break, Ruby must “de-optimize” - return control to the interpreter. It’s a safety mechanism that ensures your code always produces correct results.

Consider this method:

def add(a, b)
  a + b
end

which would generate these instructions:

== disasm: #<ISeq:add@test.rb:1 (1,0)-(3,3)>
0000 getlocal_WC_0                          a@0                       (   2)[LiCa]
0002 getlocal_WC_0                          b@1
0004 opt_plus                               <calldata!mid:+, argc:1, ARGS_SIMPLE>[CcCr]
0006 leave                                                            (   3)[Re]

Because Ruby doesn’t know what opt_plus would be called with beforehand, the underlying C function vm_opt_plus needs to handle various classes (like String, Array, Float, Integer, etc.) that can respond to +.

But, if profiling shows add is always called with integers (Fixnums), JIT compilers can generate optimized code that only handles integer addition. But it includes “guards” to check this assumption:

When the assumption is broken, like when add(1.5, 2) is called:

1. The guard check fails
2. JIT code jumps to a “side exit”
3. The side exit restores interpreter state (stack, instruction pointer..etc.)
4. Control returns to the interpreter
5. The interpreter executes opt_plus and calls the vm_opt_plus function

Other triggers for falling back include:

• TracePoint activation - TracePoint needs bytecode execution for properly emitting events (more details below)
• Redefined core methods - Someone changed what + means on Integer
• Ractor usage - Multi-ractor changes some YARV instruction’s behaviour. So the compiled code could perform differently than the interpreter in that situation

These assumption checks, or patch points as we call them in ZJIT, make sure your program performs correctly when any of the assumptions change.

Answering Some Additional Questions

Why does enabling TracePoint slow everything down?

(TracePoint is a Ruby class that can be used to register callbacks on specific Ruby execution events. It’s commonly used in debugging/development tools.)

Most of TracePoint’s events are triggered by corresponding YARV bytecode. When TracePoint is activated, instructions in ISEQs will be replaced with their trace_* counterpart. Like opt_plus will be replaced with trace_opt_plus.

If Ruby only executes the compiled machine code, then those events wouldn’t be triggered correctly. Therefore, when ZJIT and YJIT compilers detect TracePoint’s activation, they immediately throw away the optimized code to force Ruby to interpret YARV instructions instead.

Why doesn’t Ruby just compile everything?

Many methods are called rarely. Compiling them would waste memory and compilation time for no performance benefit. Also, compiling methods without profiling would mean that JIT compilers either make wrong assumptions that get invalidated pretty quickly, or don’t make specific enough assumptions that miss further optimization opportunities.

Final Notes

I hope this post helped you understand JIT compilers, a now essential part of Ruby, a little bit more.

If you want to learn more about Ruby’s new JIT compiler: ZJIT, I highly recommend giving ZJIT has been merged into Ruby a read. And if you want to learn more about Ruby’s YARV instructions, Kevin Newton’s Advent of YARV series is the best resource.

This post was originally published on July 19, 2025 on Rails at Scale.

For a decade (2014-2024), I was a Ruby-only developer. I worked across the Ruby ecosystem—from Rails development to Ruby’s core tooling like IRB, RDoc, and the debug gem. But while I moved around the stack, I stayed within Ruby’s boundaries. Ruby wasn’t just my primary language; it was essentially my only language.

That changed in 2025.

This year, I’ve contributed to Sorbet (C++), worked on RBS’s parser (C), and am now diving into ZJIT (Rust). A combination of factors enabled this shift—something I’d always dreamed of but was terrified to attempt. But AI coding tools like Cursor and Claude Code—both encouraged at Shopify—have been absolutely career-changing.

The Perfect Storm of Opportunity

Before diving into the AI aspect, I need to acknowledge two crucial factors that made this transition possible:

First, our Ruby DX team’s roadmap shifted to require Sorbet’s support for RBS, which meant I now had to work on projects written in C++ and C—system programming languages that require understanding concepts I’d never encountered in Ruby.

Second, Shopify’s Ruby and Rails Infrastructure team is packed with experts who genuinely love sharing their knowledge. Alexander Momchilov, Alexandre Terrasa, Max Bernstein, and many others have been incredibly generous with their time. Those pairing/tutoring sessions gave me the C/C++/JIT fundamentals I needed to even attempt this work.

But here’s the thing: great mentors and project opportunities to learn new languages have always existed. What’s different now is how AI has fundamentally changed the learning curve.

The Complexity of System Programming Projects

Let me use ZJIT, a new just-in-time (JIT) Ruby compiler, as an example (to learn more about it, check out this RailsAtScale post by Max). This project perfectly illustrates the challenge: it requires both deep conceptual understanding (how JITs and GC work) AND language/tool-specific expertise (Rust idioms, C programming conventions, Ruby’s build system). Working on ZJIT means constantly juggling:

1. Rust (what ZJIT is written in)
2. C (what Ruby is written in)
3. General JIT knowledge (compiler theory, optimization strategies)
4. ZJIT-specific concepts (its particular architecture and design decisions)
5. Ruby internals (how the VM actually works)
6. Ruby build systems (which have their own conventions on top of tools like autoconf and Makefile that I’d rarely encountered before)

A single pull request typically touches 2-4 of these areas simultaneously. Claude is remarkably helpful with the first three—language syntax, general concepts, standard patterns. It’s hit or miss for the last three—project-specific knowledge, deep internals, and build system quirks.

But that’s still cutting my learning blockers in half.

AI as a Complementary Pairing Partner

The real breakthrough came when I stopped thinking of AI as a code generator and started treating it as a pairing partner with complementary skills.

This isn’t about AI writing code for me. If I expected Claude to implement ZJIT features correctly, I’d likely be frustrated and probably waste more time than I’d save. The AI lacks the project-specific context and deep domain knowledge required.

Instead, we act as a pair of engineers with different strengths. While it knows more about language-specific syntax and patterns than I do, I understand the project requirements and constraints better (and hopefully have better taste). This creates a productive learning dynamic where:

• I provide task requirements and project context
• AI identifies existing patterns and acts as the language expert
• I question why certain approaches would or wouldn’t work
• AI explores the theory, either through actually changing code or simply inferring, and gives me the result
• Through the conversation, I’m learning both the language AND how to apply it effectively

For example, when I need to profile a Ruby bytecode instruction for ZJIT, I can ask Claude Code to examine previous PRs that did something similar and explain the parts I don’t understand line by line. I can ask “dumb” questions like “Why do JIT compilers need profiling?” without feeling like I’m wasting someone’s time. I get immediate clarification on unfamiliar Rust syntax. And throughout this process, I’m building my understanding of both the language and the system.

Of course, there were also times where we were both heading in the wrong direction together, and could only be saved by my mentors and teammates’ clarification and knowledge sharing. AI accelerates learning, but human expertise remains irreplaceable for course correction.

The Language Barrier Is Dissolving

What excites me most is that we no longer need to spend 100+ hours learning C before making our first contribution to a C project. AI acts as a second pair of eyes, unblocking us from silly rookie mistakes—using the wrong syntax to declare variables, misunderstanding type conventions, or fighting with unfamiliar tooling. We can start contributing meaningfully from day one, learning what we need as we go.

This doesn’t replace deep expertise—our team’s language experts remain invaluable. But it does mean that being productive in multiple languages is now achievable for more developers. The cognitive load of syntax, standard library functions, and common patterns can be offloaded, letting us focus on the actual problems we’re solving.

For someone who spent a decade as a “Ruby developer,” becoming a multi-language developer in less than a year feels revolutionary. And I suspect I’m just early to a trend that will reshape how we think about programming language specialization entirely.

• You can use the Ruby LSP extension to connect to debug.gem too. It requires a slightly different launch.json configuration (example) and provides better error handling for connection issues.

• Try using launch request in launch.json instead of attach. It simplifies the debugging process as you don’t need to manually start/stop the server. In most Rails projects, a simple entry like this will do:

  {
    "version": "0.2.0",
    "configurations": [
      {
        "type": "ruby_lsp",
        "name": "Launch Server",
        "request": "launch",
        "program": "bin/rails s",
      },
    ]
  }
  

• The effectiveness of your debugging session heavily depends on your ability to navigate between methods, classes, and files. Make sure you have a good editor setup, such as Ruby LSP.
  • Even if you don’t use VS Code, Ruby LSP works with many other editors too.
• Use Ruby LSP’s Code Lens feature to easily debug tests in both terminal and VS Code.
  • I made ruby-lsp-rspec to provide code lens for RSpec tests.

• Use gem "debug", require: "debug/prelude" in your Gemfile instead.

  debug.gem is activated when required, which usually isn’t necessary when you’re not debugging.

  By requiring debug/prelude, it defines the breakpoint methods like breakpoint and binding.break, but doesn’t activate the gem immediately.

  (This has been the default in newly generated Rails projects since Rails 7.2.)

• If you want to prevent debug.gem from being used in certain environments, you can set RUBY_DEBUG_ENABLE to 0.

  For example, setting this on CI will make debugger or binding.break raise an error rather than hang indefinitely.

• You can configure debug.gem to ignore certain gems when debugging. For example:

  begin
    # Try to load debug, but only just the config component so we don't activate it by accident
    require "debug/config"
  
    zeitwerk_paths = Gem.loaded_specs["zeitwerk"].full_require_paths.freeze
    bootsnap_paths = Gem.loaded_specs["bootsnap"].full_require_paths.freeze
  
    DEBUGGER__::CONFIG[:skip_path] = Array(DEBUGGER__::CONFIG[:skip_path]) + zeitwerk_paths + bootsnap_paths
  rescue LoadError
    # In case debug.gem is not installed for any reason
    # Such as when this file being loaded from production where debug.gem is usually not installed
  end
  

  • If you use Sorbet, you can add sorbet-runtime to the ignore list too:

    sorbet_paths = Gem.loaded_specs["sorbet-runtime"].full_require_paths.freeze
    DEBUGGER__::CONFIG[:skip_path] = Array(DEBUGGER__::CONFIG[:skip_path]) + sorbet_paths
    

• For most users, I recommend activating debug.gem’s integration with IRB for a better debugging experience. You can do this by:
  • Setting RUBY_DEBUG_IRB_CONSOLE to 1
  • Setting DEBUGGER__::CONFIG[:irb_console] to true
• The following debug.gem commands will repeat when hitting enter:
  • step (s)
  • next (n)
  • continue (c)
  • finish (fin)
  • until (u)
  • up
  • down

  For example, if you type s + enter and then hit enter again, it’ll repeat the step command.

• You can use debugger(do: "...") or debugger(pre: "...") to automatically execute a command after a breakpoint is hit:

  # This will print the local variables and open the console
  debugger(pre: "info locals")
  # This will print the local variables and continue the program
  debugger(do: "info locals")
  

• The combination of trace exception and catch [exception] commands can make debugging control-flow related bugs easier:
  • trace exception will print traces when an exception is raised
  • catch [exception] will break when the exception is raised

• Using the combination of bt [n] and up/down commands is often more effective than setting multiple breakpoints on the same code path.

• For more fine-grained tracing, you can use the tracer gem.

• debug.gem freezes all running threads when it enters a breakpoint. If this causes issues, use binding.irb as an alternative.

• You can use binding.irb for light debugging to open a REPL, and then activate debug.gem with its debug command.
• For learning more fundamental debugging concepts, I think my talk at RubyKaigi 2022 should still be helpful.

I hope you find these tips useful. Happy debugging!

Ruby 3.4 isn’t just about shiny language features; it also comes with meaningful documentation updates. Some of these changes are reflected in the content of docs.ruby-lang.org, while others are behind the scenes in RDoc, the official documentation generator for Ruby.

Documentation shapes our day-to-day experience with Ruby, as well as the first impression for newcomers. A well-structured, easy-to-read reference can:

• Decrease confusion for newcomers.
• Make day-to-day Ruby development easier.
• Encourage more community contributions.

From my previous post “A RDoc Maintainer’s View on Ruby’s Documentation”, I shared that there are many aspects around Ruby’s documentation that can be improved. So I want to use this post to summarize the improvements in Ruby 3.4 as the first step towards better Ruby documentation in the future.

I also welcome you to read the Ruby 3.4’s Documentation and Ruby 3.3’s Documentation to see the improvements.

Major Improvements in Ruby 3.4 Docs

1. Expanded Content & Indexing

As with any Ruby release, Ruby 3.4’s documentation received many fixes and improvements from Ruby committers and the community. But I’d like to highlight some changes that are unique to this release.

• A dedicated index page helps readers jump to frequently referenced classes faster (e.g., Array, String).

  

• The revamped Standard Library page makes navigating to related documentation and GitHub repositories easier.

• More than 50 dead links have been fixed with a new RDoc feature.

  

2. Revamped Theme & Navigation

• The default theme for Ruby 3.4’s documentation is more mobile-friendly, thanks to community-driven CSS upgrades in RDoc. Below is a comparison between Ruby 3.3 documentation and Ruby 3.4’s doc on iPhone.

  

  

• The color contrast, font size, and text readability have been improved.

• Class pages now feature an ancestors list (example).

  

• Source code is displayed more neatly.

  

• Direct method-linking means sharing docs with specific anchors is much simpler.

  

3. ri Improvements

The rdoc-ref expansion feature now lets “ri” automatically expand and link out to relevant information, instead of just displaying the rdoc-ref reference.

Ongoing & Future Work

As I mentioned earlier, this year’s documentation improvements are just the beginning. Even with all these changes, these are some of the ideas I’d like to explore in Ruby 3.5:

1. Reorganizing top-level pages (see PR #12226) so that non-API documents (e.g., syntax introduction, implicit conversions, etc.) become easier to find.

2. Marking default gems on docs.ruby-lang.org/en so developers can clearly see what’s part of core Ruby vs. what’s part of default gems.

   For example, ERB’s documentation page should have a badge/indicator saying it’s from the erb gem and potentially link to the gem’s repository.

3. Applying the latest RDoc features to all Ruby versions’ documentation.
4. Providing an easier way to switch between different Ruby versions’ documentation.

And other ideas that I listed in “A RDoc Maintainer’s View on Ruby’s Documentation”.

Note: Because Ruby 3.4 has been released, future documentation improvements will mostly be reflected on https://docs.ruby-lang.org/en/master/ from now on.

Community Shout-Out

We owe these updates to many RDoc contributors. A huge thanks to everyone who contributed to RDoc since Ruby 3.3 was released:

@adam12, @alexisbernard, @antoinem, @BurdetteLamar, @deivid-rodriguez, @earlopain, @eregon, @flavorjones, @hsbt, @ishe-ua, @MatheusRich, @mterada1228, @nevans, @nobu, @okuramasafumi, @omegahm, @p8, @paracycle, @sambostock, @skipkayhil, @soutaro, @st0012, @sunblaze, @tompng, @toshimaru, @vinistock, @ydah

Conclusion

As a community, we should continue to improve the documentation to make Ruby more welcoming, informative, and easy to navigate, so Rubyists can stay happy even when looking for documentation ;-)

If you’d like to contribute to the documentation, here are some resources:

• Ruby’s Documentation Contribution Guide
  • You can also contribute to this guide itself!
• RDoc’s GitHub Discussions
• RDoc’s GitHub Issues

Let’s keep the momentum going and make Ruby’s documentation the best it can be!

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.