Home > Latest topics

Latest topics > ドキュメントは善か悪か

宣伝1。日経LinuxにてLinuxの基礎?を紹介する漫画「シス管系女子」を連載させていただいています。 以下の特設サイトにて、単行本まんがでわかるLinux シス管系女子の試し読みが可能! シス管系女子って何!? - 「シス管系女子」特設サイト

宣伝2。Firefox Hacks Rebooted発売中。本書の1/3を使って、再起動不要なアドオンの作り方のテクニックや非同期処理の効率のいい書き方などを解説しています。既刊のFirefox 3 Hacks拡張機能開発チュートリアルと併せてどうぞ。

Firefox Hacks Rebooted ―Mozillaテクノロジ徹底活用テクニック
浅井 智也 池田 譲治 小山田 昌史 五味渕 大賀 下田 洋志 寺田 真 松澤 太郎
オライリージャパン

ドキュメントは善か悪か - Jul 28, 2008

ある人は、ドキュメントは悪だと言う。毎日のように何かしら変更が加わっていくソースコードの、ある一時点に対してだけの説明を書き記した物であるドキュメントは、あっという間に陳腐化する。Google等で検索すると、すでに陳腐化したドキュメントが山のように引っかかって、正しい情報になかなか辿り着けない。書く者には多大な労力を強いて、利用する者にも無駄な労力を強いる、だからドキュメントは悪なのだという。

僕は、ドキュメントは善だと思っている。ソースコードの読み方が分からない、ハチワンダイバー(将棋のマンガ。一歩退いた所から眺めてるだけでは勝てない、9×9=81マスの将棋盤の中に潜り込むくらいに集中して臨め、ということでそういうタイトルになっている)のように「ソースコードの羅列の中に潜れない」人にとっては、ドキュメントは自分に分かる言葉で書かれた唯一の資料になるから。陳腐化したドキュメントであっても、とっかかりくらいにはなる。無いよりはあった方がいい、というのが僕の考え。

というか「分かる人」(上記の話で言えば、ソースコードの中に潜れる人)の場合はソースを見ればだいたい問題は解決するので、ドキュメントがあろうと無かろうと関係ないんじゃないだろうか? 「分からない人」のために書かれた「ドキュメント」に対して、「分かる人」が「自分には邪魔だ」と言うのはいいんだけど、「万人のために悪だ」と言うのは、言い過ぎだと僕には思える。

プログラミングに限らず、絵でもなんでも。

はてブについたコメントを見て追記。

コードでhowやwhatは書けてもwhyは表現できません! は、なるほどなと思った。だからそれをコメントとしてソースコードに埋め込む必要があるのだなとも。

とっかかりが明後日の方向に向かってるドキュメントに対応してるオレはどうすれば... というのは「悪いドキュメント」に当たってしまったという事であるけれども、「自分が当たったドキュメントが悪だった」「今まで当たってきたドキュメントが悪だった」からといって「全てのドキュメントは悪だ」と言うのは言い過ぎだ、と自分はやはり思う。

分類:出来事・雑感, , , 時刻:13:35 | Comments/Trackbacks (0) | Edit

Comments/Trackbacks

TrackBack ping me at


の末尾に2014年1月19日時点の日本の首相のファミリーネーム(ローマ字で回答)を繋げて下さい。例えば「noda」なら、「2008-07-28_document.trackbacknoda」です。これは機械的なトラックバックスパムを防止するための措置です。

Post a comment

writeback message: Ready to post a comment.

2014年1月19日時点の日本の首相のファミリーネーム(ひらがなで回答)

Powered by blosxom 2.0 + starter kit
Home

カテゴリ一覧

過去の記事

1999.2~2005.8

最近のつぶやき

オススメ

Mozilla Firefox ブラウザ無料ダウンロード