Route 477

■ [ruby] RDoc書いただけで「リファレンスは完璧だお！」とか言ってるやつなんなの

タイトルは釣りですｗ。自分が実践でき(て)ないのであんまり強くはいえない。

以下、メモ書き程度だけど、個人的に、現状のRDocはユーザリファレンスに向いてないと思ってる。

問題は、

• 内部用のクラス・メソッドまで全部リストアップされてしまうこと
• どこから読めばいいか分からないこと
• クラス構成に1対1対応したリファレンスしか作れないこと

の3点。

1点目は:nodoc:付ければ解決するけど、内部用のメソッドもライブラリのメンテナ候補生にとっては有り難いものだから、 無くしてしまうのはまずい。ので、「内部用のみ」と「内部用＋外部用」の2つに分けてリファレンス作れるといいと思う。

2点目は、README(というかrdocのトップ)に、クラス構成の概要とかexampleとかをしっかり書いておけば解決できる。 「rdoc書くときは概要も書きましょう」というのを広めたい。

3点目は少し解説が必要だろう。RDocは1クラス1ページが基本だけど、ユーザ視点から見た場合、複数のクラスのメソッドを 同時に表示してほしいことがままある。例えば最近経験した例だと、Ramaze::Controller のメソッドはRamaze::ControllerとInnate::NodeとRamaze::*HelperとInnate::*Helperに分けて定義されていて、 だけどユーザからしたらそんなのはどうでもいいことで、「コントローラ内で使えるメソッド」としては これらの全部がまとめて見えてほしい。そういう柔軟な構成がRDocではできない。

まとめると、RDocはライブラリ開発者のための包括的なドキュメントを作るには向いてるけど、 ユーザ向けの親切な「リファレンスマニュアル」を作るにはあんまり向いてないと思う。 至高のユーザリファレンスのためにはクラス構造を潰せるような機能が必要で、 そのためには一から設計した新しい何かが必要。

■ [book][rails] 「600万人の女性に支持されるクックパッドというビジネス」

「Railsだってちゃんとスケールするんです！」という本でした(違う？)。 Ruby/Railsの話は少し出てくるだけですが、相当の負荷を捌いているようです。

4827550719

最近、技術系以外の話を書くサブブログを立ち上げたので(というほどまだ何も書いてないですが)、内容のことはそちらで。

• yharaの設計及び考察: 「600万人の女性に支持されるクックパッドというビジネス 」

「実装は？」と聞かれそうなブログ名だけど、実装の話はここに書くので(笑)。