Latest topics > ドキュメントは善か悪か
宣伝。日経LinuxにてLinuxの基礎？を紹介する漫画「シス管系女子」を連載させていただいています。
以下の特設サイトにて、単行本まんがでわかるLinux シス管系女子の試し読みが可能！
ドキュメントは善か悪か - Jul 28, 2008
ある人は、ドキュメントは悪だと言う。毎日のように何かしら変更が加わっていくソースコードの、ある一時点に対してだけの説明を書き記した物であるドキュメントは、あっという間に陳腐化する。Google等で検索すると、すでに陳腐化したドキュメントが山のように引っかかって、正しい情報になかなか辿り着けない。書く者には多大な労力を強いて、利用する者にも無駄な労力を強いる、だからドキュメントは悪なのだという。
僕は、ドキュメントは善だと思っている。ソースコードの読み方が分からない、ハチワンダイバー（将棋のマンガ。一歩退いた所から眺めてるだけでは勝てない、9×9＝81マスの将棋盤の中に潜り込むくらいに集中して臨め、ということでそういうタイトルになっている）のように「ソースコードの羅列の中に潜れない」人にとっては、ドキュメントは自分に分かる言葉で書かれた唯一の資料になるから。陳腐化したドキュメントであっても、とっかかりくらいにはなる。無いよりはあった方がいい、というのが僕の考え。
というか「分かる人」（上記の話で言えば、ソースコードの中に潜れる人）の場合はソースを見ればだいたい問題は解決するので、ドキュメントがあろうと無かろうと関係ないんじゃないだろうか？ 「分からない人」のために書かれた「ドキュメント」に対して、「分かる人」が「自分には邪魔だ」と言うのはいいんだけど、「万人のために悪だ」と言うのは、言い過ぎだと僕には思える。
プログラミングに限らず、絵でもなんでも。
はてブについたコメントを見て追記。
コードでhowやwhatは書けてもwhyは表現できません！
は、なるほどなと思った。だからそれをコメントとしてソースコードに埋め込む必要があるのだなとも。
とっかかりが明後日の方向に向かってるドキュメントに対応してるオレはどうすれば...
というのは「悪いドキュメント」に当たってしまったという事であるけれども、「自分が当たったドキュメントが悪だった」「今まで当たってきたドキュメントが悪だった」からといって「全てのドキュメントは悪だ」と言うのは言い過ぎだ、と自分はやはり思う。
Comments/Trackbacks
TrackBack ping me at
の末尾に2020年11月30日時点の日本の首相のファミリーネーム（ローマ字で回答）を繋げて下さい。例えば「noda」なら、「2008-07-28_document.trackbacknoda」です。これは機械的なトラックバックスパムを防止するための措置です。
Post a comment
writeback message: Ready to post a comment.