青木日記

■ Ruby勉強会＠関西12

京都は近かった。 こないだ 24 時間近く飛行機でかかったのと比べると、 2 時間半なんてあっというまでした。 ちょっと寝てたら着いちゃったもんな。

勉強会の規模が毎回大きくなってるてのは聞いてたけど、 いまはずいぶんでかくなってるんですね。 今回は 60 人くらいだったっけ。 にぎわっているのはいいことだ。

自分のセッションの内容はこのあと書くので略。

自分の以外のセッションは、まず、 かずひこさん & 京都女子大生s による TDD 講座、 znz さんによる "about Nadoka"、 あとは小波ゼミ生による発表、という内容でした。

一番おもしろかったのは TDD 講座かな。 ペアプロやったのなんて初めてだ。 けっこう難しいもんですね。

勉強会のあとは、定例の場所らしい飲み屋で一次会 (20:00 ごろまで)。 駅までのバスが女子高生で埋め尽くされており、 その対応によってそれぞれの本性が垣間見えた。 飲み会では、リファレンスマニュアルの話もしたが、 その他になぜか哲学で話が弾んだりした。

続いて根性のある人達による二次会 (23:00 ごろまで)。 まだ飲み続ける。

さらに、もう帰れない人達と、いつでも帰れる人達による、 夜を徹した三次会 (03:00 ごろまで)。 なぜかまたしても哲学で話が弾む。 そういえば cuzic さんは家に帰れたのだろうか。

最後は、もう帰れない人達 (Youhei さん、にしはたさん、青木) が漫画喫茶で夜明け待ち。 ドラゴンボールをギニュー特戦隊からブウ編まで読んだ (その暇に寝ろって話もある)。

そのあとは一人で京都観光しようかと思ってたんですが、 さすがに力尽きたので清水寺だけ参拝して帰宅。 朝の 8 時だというのに観光客はいるし、 ちゃんと八つ橋屋も開いてるし、さすが京都だと思った。 買わなかったけどな。

(21:09)

■ Ruby勉強会＠関西12「Rubyリファレンスマニュアル刷新計画」要旨

自己紹介は略

[Ruby リファレンスマニュアルとは]

• http://www.ruby-lang.org/ja/man/
• Ruby言語仕様
• Rubyの文法
• クラスリファレンス
• FAQ など、たくさんの付録

[Ruby リファレンスマニュアル刷新計画とは]

• このリファレンスマニュアルを全面的に刷新する計画 (そのまま)
• なぜ刷新するのか？ → 現状のリファレンスマニュアルに不満があるから

[リファレンスマニュアル 10 の不満]

• 書きかけのドキュメント、足りないドキュメントがある

「Ruby言語仕様」とか。 もっとも、これは青木が書きかけで放置したのが最大の原因である。

あとは、標準添付ライブラリのリファレンスが足りない。

C API リファレンスは見ることすらできなくなっている。

• 全体の統一感がない

語尾が揃ってないとか、重複するドキュメントが多いとか。 例えば「FAQ」と「Rubyの落とし穴」は意味的に重複する。

• 文章の質が低い

$stdin のエントリの例を引いて説明。 いろいろなことを同時に説明しようとしているせいでわかりにくい。

• 複数の Ruby バージョンの記述が混在していて読みにくい

自分が知りたいのは特定バージョンの Ruby の仕様だけなのに、 1.6 から 1.9 まで全部ごちゃまぜに書いてある。

• デザインが気に食わない

気に食わない。

• メソッド検索がヘボい

いまはただのテキスト検索でしかない。 ReFe レベルの検索ができるようにしたい。

• ライブラリによるメソッドの追加、上書きに対処できない

上記の不満に比べれば些細なことではあるが、 できれば対処したい。

• 記述形式がファイルごとにバラバラ

一つのメソッドシグネチャの記述だけで 5 種類あったりとか。 標準添付ライブラリはファイル構成も明確な規準がない。

• 内容の自動化が難しい

記述形式がバラバラ → ちゃんとメタデータが取れない → クラスツリーなどが自動生成できない

• ドキュメントのファイルに直接アクセスできない

sed で全部処理だー、とか思っても、できない。 300 近いファイルを全部手でいじらなければならない。

[解決策]

• RWiki を捨てて独自の新システムを構築する
• 全コンテンツを統合、再編成する
• 文章の質はがんばって改善する

以下詳述

[解決策1： 新システム BitClust]

• ドキュメントは Subversion で管理
• 上記の問題に対処できるファイル構成
• メタデータをきっちり取れる厳格なフォーマット
• 複数の Ruby バージョンにフォーマットレベルで対処
• メソッドの追加や上書きにも対応
• Wiki ではないので、ウェブからは編集できなくなる

※ 最後の点については、制限というよりは仕様であるという認識。 この点を補うアイデアとして、Wiki のようにウェブ上から編集すると、 その diff がメンテナに送られるというサブシステムを提案する。 メンテナはその diff を読んだうえで、取り込むかどうか決める。

[解決策2： コンテンツの再編成]

• Ruby 言語仕様 (旧「言語仕様」+ 旧「文法」)
• クラスリファレンス (組み込み + 標準添付)
• 拡張ライブラリ API リファレンス
• FAQ などは分離する

[解決策3： 文章の質の改善]

• 担当制：ファイルごとにメンテナを明示して、責任の所在をはっきりさせる
• 記述規約：書籍執筆のノウハウを生かして、かなり細かく規約を決めてしまう
• メンバーの教育制度？ (規約が細かくなると、教育が必要かもしれない)
• あとは根性でガンガレ

[目標]

• Ruby 1.8.6 or 7 リリースと同時に、抜けのない完全なリファレンスマニュアルをリリースする
• ウェブ版、スタティック HTML 版、HTML Help 版、(info 版？)、ReFe データベースを同時リリースする
• できれば、そのまま本にできる品質で (これは現実的に無理だと思うので要求しない)

[現状]

• BitClust は主要部分がすでに完成
• 組み込みライブラリのリファレンスはほぼシステムの移行が完了
• 標準添付ライブラリのリファレンスもほぼ移行完了
• C API リファレンスもたぶんすぐに移行できる

ドキュメントの変換は、伊達さん、sheepman さん、岩月さんが がんばってくれたおかげでめちゃめちゃ進んでます。 残ってるのはほぼわたしが止めているという体たらく。

[課題]

• リファレンス以外の部分はほぼ手つかずなので、これをなんとか書く
• リファレンスをすべて揃える
• BitClustのユーザインターフェイスを改善する
• かっこいいデザイン

[人材募集]

• Ruby がわかる人 → リファレンスを書く
• 人に読ませる日本語が書ける人 → リファレンスを改善する、ドキュメントを書く

[参加方法]

• まず ruby-reference-manual ML に入る。
• ML への参加方法： 以下のアドレスへ適当になんかメールを送る (そのメールも配信されるので注意)

To: ruby-reference-manual ＠ ml.fdiary.net
Cc: aamine ＠ loveruby.net

• Subversion アカウントが欲しい人は青木個人宛にメールする

(21:37)