- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- （メソッドor関数の詳細など）
- SEE ALSO
- AUTHOR
- COPYRIGHT
require LWP::UserAgent;
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->env_proxy;
my $response = $ua->get('http://search.cpan.org/');
if ($response->is_success) {
print $response->content; # or whatever
}
else {
die $response->status_line;
}
これを見ただけで「そうか，このモジュールだとこんなに簡単にWebページを取得することができるんだな」というのがまず分かる。これで「このモジュールで何ができるのか」を最初に示すことで興味を惹きつけることができた。
何をやっているのか，これだけで分からないとしても次のDESCRIPTIONで補足できるだろう。
興味を持ったユーザは，このSYNOPSISをもうちょっと読んで「このモジュールはnewしてtimeoutとかを設定してgetをするんだな。そうするとresponseという別のオブジェクトが返ってくるのだな。getの詳細を見てそっちのドキュメントも読む必要があるのかな」というくらいのことが読み取れる。
モジュール動作を理解するきっかけになるメソッド名を教えることができた。
その直後にメソッドの詳細説明があるが，ユーザはまず上で出てきたメソッドから読み始めることができる。
滅多に使わないメソッドは後で読むことができる訳だ。
ここまで来たら後はもう放っておいてもユーザはドキュメントを隅から隅まで読み始めるだろう。
AUTHORを見て「この人は他にどんなモジュールを使ってるのかな」とか，COPYRIGHTを見て「よし，次の案件に使おう」とか思うようにもなるかもしれない。
そして，不幸にしてユーザが探しているのがこのモジュールでは無かったとしても，早い段階で「ああ，これは違うな」と判断することができる。
では，これが逆順だったら？
COPYRIGHTを見て「うるさいな，まだ使うかどうかも決めてないのに」と思い，AUTHORを見て「名前見ても分からないよ」と思い，大量のメソッドの詳細にうんざりし，ようやく何ができるのか，どうやって使うのかが見つかる。
しかし，そこまで根気良く読み進めるユーザがどれだけいるだろうか？ 途中で投げ出してしまうユーザがほとんどだろう。
以上のように，Perl/CPANモジュールのドキュメントの読みやすさにはこの'順番'も一役買っている。そして，podの中ではSYNOPSISの書き方こそがもっとも重要と言っても良いかもしれない。
Trackback URL for this post:
http://www.typemiss.net/trackback/54
