rurema / doctree

Repository of Japanese Ruby reference manual
https://docs.ruby-lang.org/ja/
242 stars 312 forks source link

Ruby に関するドキュメントを英語のものと日本語のもので統合する #2887

Open Paalon opened 1 month ago

Paalon commented 1 month ago

まず、前提として、私は普段 Ruby を書いていないし(Ruby を書く母には育てられました)、Ruby の歴史にも詳しくないし、Ruby のドキュメントの歴史にも詳しくはないです。ですが、外から見て不思議に思ったのでイシューを建てさせてもらいます。

Ruby の公式ドキュメントで Object#class の項目を探そうとしたときに、英語版と日本語版のドキュメントがあることを https://docs.ruby-lang.org/ で知ります。そして英語版のドキュメントの Object の項目で探しますが見当たりません。次に日本語のドキュメントを開くと、英語版と全く異なるスタイル・内容で Object#class の項目も見つかって英語版よりもよく書かれています。Discord の Ruby コミュニティに尋ねたところ、英語版には Kernel#class にその項目があるようだと言われます。どうやら日本語版のドキュメントの方が信頼できそうだということは分かったのですが、ドキュメントの維持の労力が英語と日本語で別々に割かれているのでは、良くないし、英語しかできない人も利用したいねという話になりました。(Kernel#classObject#class の記述のどちらが適切な配置かはあまり Ruby に詳しくないためよく分かっていません。https://github.com/rurema/doctree/issues/2664)

Ruby のドキュメントがここ (rerema/doctree) と https://docs.ruby-lang.org/en/3.3/index.html のもの(どこにホストされているのか分からない)の2つに分裂している歴史的背景をあまり知らないので的外れかもしれませんが、どうにか統合もしくは英語版を提供できた方が良い思ったため、このイシューを建てさせていただきました。

znz commented 1 month ago

とりあえず歴史や現状は無視して、どういう状況になったら統合できていると思いますか?

参考にしたいので、多言語版が統合できていると思うようなドキュメントの例はあれば教えてほしいです。

Paalon commented 1 month ago

私は普段 Julia をよく触っているのですが、ドキュメントの完成度は低いかもしれませんが(日本語版の充実度は Ruby がプログラミング言語中で1番だと思うので)、Julia のドキュメントの非英語版は大抵英語版と同じスタイルを使っています。

リファレンスではありませんが、Rust のものもスタイルは同じものを使っています。

Paalon commented 1 month ago

多言語版をビルドする方法を用意しておいて、あとは翻訳するだけという状態にしておけば、少なくとも英語版と日本語版は統合されていると言えるようにできるのではないでしょうか。