= ruby-reference-manual summary, 2006-02-27〜2006-03-22

== ToDo

(1) カテゴリ分け (ってまだならサマリ出すなよ > SugHimsi)

指摘抜け・分け方違い大有りなものですが:

* 内容の充実
  * 項目の取捨
    * 補填
      * YAML, REXML, etc.
    * 重複枚挙
    * 存在意義問い直し
      * 「執筆者募集」
      * 「Ruby言語仕様」
    * 過去のv.対応
  * 項目相互の連関
    * 継承関係の抽出方法
    * スーパークラスのメソッド埋込
    * RDocとの連携
    * 逆引き対応
    * データベース化
  * 内容の編集方針
    * 「判りやすさ」の追求
      * 対象読者の知識水準の確定?
    * 変更
      * 定型処理対応
      * v.up対応
      * 校正基準
    * 追加
      * 説明の完備性担保
      * 信頼度情報の附加?
    * 削除
  * 翻訳対応
    * 英仏独西葡CKJV
* 統一性
  * フォーマット
    * 階層明記
    * クラス?メソッド?etc.明記
    * 一覧性
      * ページの単位
      * 文章と箇条書きの重み付け
      * 辞書順整列
    * 検索対応
      * パーズしやすさ
      * packやREやsprintfの扱い
      * Google
    * タグ
    * RSS/Atom対応
    * サンプル
    * 画像
      * キャプチャ画面
  * スタイル
    * ページ名(日本語是非)
    * レイアウト
      * メソッドサマリ一覧
      * サイドバー?
    * 文体
  * デザイン
    * CSS
    * 色相
* その他
  * Open or Closed
    * 表玄関は静的に?
    * 検索インタフェース
  * 広報宣伝
    * サイト誘導
      * 関連サイトから?

(2) 編集方針固め
(3) 担当アサイン
(4) 見直し・追加…の原稿作成
(5) 原稿一次締切
(6) 再サーベイ、再アサイン
(7) 全体締切
(8) β版編集
(9) レビュー
(10) 正式公開、広報

以下、まとめただけ。

== Rubyリファレンスマニュアルの便利な点
[:04]
  * 変更に勝手に追随してくれる
[:02]
  * 日本語が備わっている
  * 索引がある
  * 文句を言いやすい
[:05]
  * ネット上にあって、いつでも手軽に参照できる
[:05]
  * 用例が多い
[:06]
  * 実は大きな不満は少なかったり
    * 特に組み込みオブジェクトの部分に関しては
      記述のスタイルも内容量も統一されていて読み易い
[:07]
  * プログラミングの下地があれば参照しつつ
    Rubyを弄りませる程度には情報がそろっている
  * サンプルソースが多めで有用
[:08]
  * さっと検索できる
    * manの場合「どのmanページ?」ということがしばしばある
[:11]
  * 日本語で一通り読める
  * 気づいた点があったらWikiなので直せる
[:13]
  * 全文検索は便利
  * サンプルソースが多いのでうれしい
[:14]
  * 用例が比較的多い
  * packテンプレートと正規表現がまとまっている
[:15]
  * ダウンロードしやすい
  * サンプルコードなど、参考になる記述が多い

[:16]
  * 普段は「Windows HTML Help版」を使っているが、
    クラスのメソッドを調べるのが便利
  * またメソッドの解説がわかりやすい
[:17]
  * 基本的な情報がかなり網羅されている感じ
    * 普段はriやReFeでメソッドを調べて、
      そこから派生した情報などを知りたい時などに利用
  * 情報を手軽に修正できる、とくにRDで記述されているのは
    個人的にかなりうれしい
[:18]
  * refe で引ける
    * とても便利です
[:19]
  * これが無いと話にならない、生きていけない

== Rubyリファレンスマニュアルの不便な点
[:04]
  * ときどき「わかりにくい」と文句を言われること。
[:02]
  * リニューアルの動きがなかなか功を奏さない
  * 実際いったん直すとなるとちょっと大掛かり
  * 英語RDocとの連携がない
[:05]
  * 陳列の仕方がベタだ。
  * 説明が完備していない。
  * 「執筆者募集」がいまいちよく分からない
    * 今もそうなのか、ただの作業残骸なのか、何をどうするのか
  * 検索がぜんぜん便利じゃない
    * いっそGoogleに
[:05]
  * 組み込みと標準添付とC APIのリファレンスがバラバラ
    * いまC APIは見ることすらできない
    かなりたくさん書いたので、データだけでも救出したい
    [:09] RDPに置いてあったということでしょうか?
  * ウェブ上でメソッドを検索したい。
    [:09] ブラウザの検索機能に頼るので良ければ
          メソッド一覧ページあり
  * RWikiだと全体にまたがる定型処理ができなくて不便
    [:09] バックエンドをsvnにしてレポジトリを公開して、
          wiki以外からもcommitできるようにすれば
          解決できそうなのですが、svn bindingが
          sargeのsvnだと使えなくて困。
  * RWikiだとページ名が変えにくい。
    [:09] ページ名変更機能あり
          mediawikiのようにredirectが欲しいということ?
  * RWikiだと日本語ページのURLが汚い
    [:09] ページ名の規則の問題
[:06]
  * 添付ライブラリの部分は
    記述にばらつきがあったり
    リンクだけだったりするものがあったりするので、
    やはり重点的にその辺りを何とかしたほうがいいのかな
[:07]
  * 細かい検索ができない
[:08]
  * とりあえずRuby/Tkのマニュアルをどうにか
[:08]
  * メソッドが多いクラスでは、目的のメソッドに辿り着くのに
    手間取ることがある
  * alias名などの場合、辞書式順序にならんでいないことがある
  * ライブラリによって記述や充実の程度に極端に差がある
[:11]
  * 添付ライブラリはマニュアルが無いものがある
    (YAMLやREXML等)
  * あるバージョンのRubyに対応したマニュアルが見れない
  * Wikiなので直せるのはいいが、
    自信が無くても、また、誰でも変えられてしまう。
    (PHPのマニュアルのように、noteを追記できるようにしたら?)
[:13]
  * 不便というか、文章や構成に統一感はないと思う
[:14]
  * 一覧性が低い
    * トップから組み込みクラスにたどりつくまで 
      リンクを2回たどらないとならない
      * 行き来すると段々イヤになってくる
    * 単にサイドバーなりがあれば良いのかも
  * スーパークラスのメソッドが埋め込まれていない
    * File#putsを探すためにFileを見て、無いので
      今度はIOを見なければならない
  * マウスを利用したブラウズだけでは済まなくて
    結局、検索―ブラウザ機能、サーバ提供を問わず―
    のためにキーボードを利用することになる
    * 特にStringのようにメソッド数が多い場合
[:15]
  * 既存のクラス・メソッドの資料が見つからないことが多い
  * 構文に関する記述が少ないと感じました
  * Javadocに慣れていたため、当初ちょっと戸惑った
    * ページ上部にメソッドのサマリーがあるといい感じ
[:16]
  * C言語を知っているくらいの知識で読むと
    理解出来ない部分が多かった
    * Ruby言語仕様のあたりとか
[:17]
  * 個々のメソッドの説明が文章の集まりなので、
    必要な情報を探すのに文章全体を読み込まないといけない
    * あるメソッドの戻り値だけを知りたい場合などに面倒
  * 1ページが長く、複数の事柄を一度に書きすぎている感じ(たまに)
    * メソッドを検索して、該当するページを表示しても、
      さらにそこからページ内のメソッド名を検索する二度手間
[:18]
  * リファレンスがないライブラリがある
  * 外部リファレンスへのリンクだけが
    公式リファレンス上にあるライブラリだと
    refeで引けない
  * 何の単位でページが作られているのかが
    ライブラリによってばらばらで分かりづらいところがある
    * 添付ライブラリ
      http://www.ruby-lang.org/ja/man/?cmd=view;name=	\
      %C5%BA%C9%D5%A5%E9%A5%A4%A5%D6%A5%E9%A5%EA
      において、
       date 日付クラス
      というリンクをたどると
       --> Date
       --> DateTime
      というのが出てきますが、それが何なのか分かりづらい
      * 実際にはクラスであるが、リンクをたどった末に判ること
[:19]
  * あんまり感じません
  * 「Ruby言語仕様」と「Rubyの文法」の違いがわかんなかったり
  * 拡張ライブラリで、時々マニュアルがないのがある
  * でも、それぞれ使い方やチュートリアルがあると便利

== その他リファレンスマニュアルについて思うこと
[:04]
  * そういえば自分ではあまり使ってません。
[:03]
  * デザインについて:
    今のCSSは以前のものを引き継いでいるだけで、
    特にこだわりはないので、
    tDiary互換とかもないので、
    別のものを提供して頂ければ
    すぐにでも変更してもかまわない
    HTMLの変更要求とかがあっても対応できます。
[:02]
  * <http://cvs.m17n.org/%7Eakr/diary/2006-02.html#a2006_02_25>
    は(Tropy移行とかしなければ)問題にならないと思う…
  * <http://ch.kitaguni.tv/u/5250/%a4%bd%a4%ce%c2%be/0000281323.html>
    は奇特な意見と思っておいたほうがいいか?
[:05]
  * 言語のリファレンスらしい検索手順がないものかなあ。
[:05]
  * 「Ruby言語仕様」をどうにかしたい。書くか、捨てるか。
    [:09] 編集用Wikiと公開用のstaticなページを分けるときに
          書きかけのものは公開用に反映しないということが
          出来ると良いかもしれない
  * ((|...|))タグがウザい
    引数なんて自動的に検出できるんだから自動で付ければよい
  * (({...}))タグもウザい。これも大部分は自動化できるはず
    [:09] MethodListは自動で付けていますが、
          他にどこで自動的に検出できるのでしょうか?
  * 「Ruby 1.x feature」のタグ付けが統一されておらず見苦しい
    [:09] 現状は
        * 個別のMethodListの末尾(別名が増えた場合など)
        * 説明の先頭(メソッド自体が増えた場合など)
        * 説明の途中の段落の頭(メソッドの仕様変更など)
  * RWikiデフォルトのCSSが嫌い
    [:09] 代わりを募集したい
  * (ReFe) データベースを定期的に自動生成できるようにしたい
    [:09] これは公開用のstaticなページと一緒に自動生成したい
  * (ReFe) どのファイルがリファレンスなのか自動判別しにくい
    [:09] 現状はページの先頭に`###nonref'というものが入っている
          ページがありますが、完全ではなさそう
  * (ReFe) パースしにくい。フォーマットを統一してほしい
    [:09] パースしやすいフォーマットを提案してほしい
  * (ReFe) クラスの継承関係を機械的に抽出したい。いまは全部手書き
    [:09] これが機械的に抽出出来るようになると、
          RWiki側でも継承元も含めたメソッド一覧などが作れる
  * (ReFe) いまはsprintfフォーマットやpackテンプレートを
           特別扱いして検索できるようにしているが、
           もっと統一的に処理できるようにしたい
[:06]
  * 新リファレンスの公開版に関しては
    静的なコンテンツで、という話がありましたが、
    それとは別途に
    使いやすい全文検索のインターフェースも用意したい
[:07]
  * 主にWindows上での簡易的なツール作りに使う為か、
    Windows特有の動作などで躓くことが多々あったため
    その辺りの情報についてもう少しどうにかならないか
[:08]
  * 最初に思うのは常に「ごめんなさい!」
[:11]
  * 日本語以外のことを考えると、
    rdocも並行して整備しないといけないのかも
    * ライブラリを作る段階でrdoc書きましょう、と
[:14]
  * グレー地に黒のテキストと青いリンクは読みやすい
[:15]
  * 英語のマニュアルも充実させたい
[:16]
  * デザインが安っぽく見える
    * ただし読みにくいとは思わない
  * 一貫した難易度(対象者の知識量)の基準がほしい
[:17]
  * 1ページが長く云々は、必ずしも悪いことではないが
    リファレンスマニュアルを見るときには
    そのメソッドが属するクラス全体を一度に知ろうと
    思うことが経験上あまり無く、一部メソッドの機能や
    仕様、応用例などを知りたいと思うことの方が多かった
  * もっと小刻みに情報が欲しいことがあります。
    Web版riやReFeというイメージ
  * RSSにおいて一つのページの編集履歴が
    最新の物しか参照できないような(勘違い?)
    * 更新頻度の高いページの差分を見たときに気になって、
      そのあと実際にRWikiで編集履歴を確認することもあり
[:18]
  * 欠けている項目があるなどの不備もいろいろとあるのですが、
    refeの存在がそれらに対する不満を打ち消すくらいお気に入り
[:19]
  * まずはリファレンスマニュアルへ誘導する環境づくりか
    * ウェブサイトとか
  * 逆引き系も、オフィシャルにやると嬉しいことが多いかも

-- 
SugHimsi == SUGIHARA Hiroshi
maili31s at CLIO-Net

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/