Ruby のドキュメント、Python のドキュメント、PHP のドキュメント

Pythonのマニュアルは、Rubyのリファレンスマニュアルより、ずっと良い

Python のマニュアルは量が多いのは分かっているけど真面目に見たことないのでなんとも言えない。ただ、Ruby のリファレンスマニュアルがなんだか微妙だという印象は強い。まつもとさんはまぁまぁだと思っているみたいだけど、個人的には「リファレンスマニュアル

• 逆引き Ruby」でまぁまぁかなと思っている。

とにかくリファレンスマニュアルは記述が質素すぎて自分のほしい情報への取っ掛かりにしにくく、Namazu で検索してもタイトルでは意味がまったく分からないことが多いような気がする。ページをもう少し細かく分けた方がいいのかもしれない。¹PHP のマニュアルのようにものすごく大量なのもそれはそれで確かに扱いにくいんだけど、検索に関して言えば PHP の方はほぼ目的のものが一発で見つかるので助かる。

あと凡例のページを用意してほしいかな。ソースコード内で意味を持ちそうな記号を説明用の記号として使っているので、どこからが説明でどこまでコードなのか判別しにくい。あるいはソースコードをハイライトする RWiki のプラグインのようなものがあればよいのかもしれないけど。よくサンプルコードを見て首をひねってしまう。

Ruby に慣れていれば「こんな記号に意味はない」と一発で分かるんだろうけど、そういう人はそんなにリファレンス見ないと思うんだな。その辺の書き手と読み手の意識のずれが Ruby 関係のドキュメントをよりよくしようとする際のカギなのかもしれない。