こんにちは。ruremaメンバーの id:Pocke です。
Rubyの日本語リファレンスマニュアルで、未翻訳の英語のドキュメントが公開されるようになりました。 この記事では、それについて簡単に解説します。
何が変わるのか
今までは、未訳のメソッドは日本語リファレンスマニュアルには一切書かれていませんでした。 それが今回の変更によって、英語のリファレンスマニュアルと同じ文章が、そのまま日本語リファレンスマニュアルにも書かれるようになります。
たとえば Ruby 2.7で追加されたModule#const_source_locationメソッドのドキュメントは未訳であるため、今までは日本語リファレンスマニュアルにはドキュメントが存在しませんでした。
ところが今回からは次のようなドキュメントが日本語リファレンスマニュアルにも存在するようになります。
https://docs.ruby-lang.org/ja/latest/method/Module/i/const_source_location.html
なお、現時点(2020-07-08)ではRuby 2.7で組み込みライブラリに追加された未訳のメソッドのみ英語ドキュメントが追加されており、その他の標準ライブラリの変更などは反映されていません。
なぜ未訳のドキュメントを公開するのか
公開することで、ドキュメントを読む人、ドキュメントを書く人、そしてドキュメントを管理する人のそれぞれに利点が生まれると考えています。
ドキュメントを読む人
まず、ドキュメントを読む人にとっては「メソッドが存在することを知れる」というのが一番の利点だと思っています。 今までの未訳のメソッドのドキュメントはなにも存在しませんでした。そのためドキュメントを読みに来た人はそのメソッドが存在することすらわかりません。
今回の修正によって、未訳のメソッドのドキュメントが公開されるようになります。 英語のドキュメントを読む必要はありますが、なにもドキュメントがないよりはよっぽど良い状態だと考えています。
また、 https://docs.ruby-lang.org/ja/latest/doc/news=2f2_7_0.html のような NEWS からの未訳のメソッドへのリンクがリンク切れにならないという効果もあります。 (これはznzさんに指摘してもらいました。)
ドキュメントを書く人
そして、ドキュメントを書く人にとっても利点があります。 日本語リファレンスマニュアルは多くの場合、英語のリファレンスマニュアルを参考にして書かれています。 そのため参考となる英語のリファレンスマニュアルが書かれていれば、それを見ながら日本語を書くことができ、作業効率の改善が予想できます。
ドキュメントを管理する人
最後に、ドキュメントを管理する人にも利点があります。
今までは未訳のメソッドはGitHub Issue(例: https://github.com/rurema/doctree/issues/2071 )で管理され、有志の手によってドキュメントが書かれていました。 この進捗はあまり芳しくなく、Ruby 2.7で追加されたメソッドにも未訳のものが多く残っています。
未訳のものが多く残る原因はいくつかあると思いますが、その1つに「多くの人は未訳のドキュメントがあることに気がついていない」ことがあるでしょう。 GitHub Issueで管理されているとは言え、それはドキュメントをただ見に来る人にはあまり縁のない情報です。
それが英語でドキュメントを公開することによって、少し変わったら良いなと思っています。 日本語リファレンスマニュアルを読んでいて英語のドキュメントに出会った時に、そのドキュメントの日本語化に力を貸していただけたら幸いです。
