Joel on Software   このページは"ジョエル・オン・ソフトウェア

※新しい翻訳はJoel on Software Translation Projectにあります。

その他の "Joel on Software" の記事（日本語）

その他の "Joel on Software" の記事（英語）

著者へのメール（英文のみ）

さて、私たちはなぜ仕様書が必要なのか、仕様書の中身は何か、そして誰がそれを書くべきかについて話してきた。このシリーズの最後のパートでは、良い仕様書を書くためのアドバイスをお話ししよう。

仕様書を実際に書いているチームから聞く最大の不平は、「誰も読まない」ということだ。誰も仕様書を読まない場合、それを書いている人たちはひがみっぽくなる。エンジニアが4インチの厚さの仕様書の山を使ってキュービクルを拡張している昔のディルバートの漫画みたいなものだ。典型的な官僚的大企業では、みんな何ヶ月もかけて退屈な仕様書を書いている。仕様書が出来上がると、それは棚に収められ、再び取り下ろされることはなく、製品は仕様書に書かれていることとは無関係にスクラッチから実装される。それは誰も仕様書を読まないからで、そしてなぜ誰も読まないかと言えば、仕様書があまりに退屈でつまらないからだ。仕様書を書くプロセスは、少なくともその問題についてつくづく考えることを強いるので、良いエクササイズともなり得たのだが、しかし仕様書が完成すると棚に収められる(読まれないし、愛されない)と言う事実は、それがまったくの徒労であるように人々に感じさせる。

また、もし仕様書が決して読まれないなら、完成品が出荷されたときに多くの問題が生じるだろう。誰か(マネジメント、マーケティングあるいは顧客) が言う:「おい、ちょっと! 君はあさり蒸し器がついていると言ったはずだ! あさり蒸し器はいったいどこにあるんだ?」それに対してプログラマは答える。「それは違います。仕様書の第3章、4節、パラグラフ2.3.0.1を見ていただければ、『あさり蒸し器はついていない』とはっきり書いてあります。」しかしこれでは顧客は納得せず、顧客はいつでも正しいので、不平たらたらのプログラマはあさり蒸し器を後付しなければならなくなる(そして彼らはさらに仕様書に対して懐疑的になる)。あるいはマネージャが「おい、このダイアログの言い回しはくどすぎるぞ。それにダイアログは全部上に広告を入れることになっているだろ。」するとプログラマは怒って「だけどおたくは仕様書を承認したし、そこにはダイアログのレイアウトと中身がはっきりと書いてあったはずだ。」と言う。しかしもちろんマネージャは仕様書を実際には読んでない、なぜなら彼が読もうとすると、彼の脳みそは眼窩から滲み出してしまうし、まあ何にしても、それは火曜日のゴルフゲームには邪魔になるからだ。

仕様書はいいものだが、誰も読まないのであればそうはならない。仕様書書きとしてのあなたは、うまくだまして人々がそれを読むように仕向ける必要がある。そしてすでに小さすぎる脳みそが眼窩から漏れ出さないように、力を注ぐ必要がある。

人々にあなたの仕様書を読ませる仕掛けは、通常は良い文章を書くという問題と同じだ。しかし単に「いい書き手になれ」と言って放っておくのはフェアじゃないだろう。仕様書を読んでもらえるようにするために、あなたが従わなければならない4つの簡単なルールを以下に挙げる:

ルール1: ユーモア

そう、人々にあなたの仕様書を読ませるためのルールの第1番は、読むのが楽しくすることだ。面白い人間に生まれついてないなんて言わないで、信じないから。誰でもおかしな考えをいつも持っているものだが、「専門的でない」ということで自己検閲しているのだ。ふぅ、たまにはルールを破ることも必要だ。

私がこのWebサイトに書いたごみの山を読んでもらえたなら、おかしくしようとする下手な試みがそこら中に散らばっているのに気づくだろう。ほんの4パラグラフ前に、汚い体液のジョークでゴルフをしているマネージャを茶化したばかりだ。実際にはそんなに面白くなかったとしても、私は非常に熱心に努力しているし、おかしくしようとしてじたばたしている行動自体、悲しい道化のように楽しめるものだ。あなたが仕様書を書くとき、簡単におかしくできる部分は例を示すところだ。ある機能がどう動くか説明するのに、

• ユーザはCtrl+Nをタイプして新しいEmployeeテーブルを作成し、従業員の名前を入力する。

と書くかわりに、

• ピギー嬢は、彼女のまるまるした小さな指は太すぎて個々のキーが押せなかったので、アイライナー・スティックを使ってキーボードを突っつき、Ctrl+Nとタイプして新しいBoyfriendテーブルを作成し、レコード"Kermit"を1件だけ入力した。

のように書いてみよう。

デイブ・バリーを読めば、おかしくするためのもっとも簡単な方法は、必要もないのに話を特定のことにすることだと分かるだろう。「向う意気の強いパグ」は「犬」よりもこっけいだし、「ピギー嬢」は｢ユーザ｣よりもこっけいだ。「特別利益団体」と言う代わりに「左利きのアボカド農家」と言い、｢飼い犬の糞を始末しない飼い主は罰せられるべきだ」と言う代わりに、「彼らはあまりに孤独で受刑者たちはクモをセックスのために支払わなければならない監獄に送るべきだ」と言おう。

それと、もしおかしくすると専門的でなくなってしまうと思っているなら、ごめんなさい、それはあなたがユーモアのセンスを持ってないだけのことだ。 (否定しないで。ユーモアのセンスのない人たちはみんなそれを否定する。私は騙せませんよ。) そしてもしあなたが、陽気でおかしく読んでいて楽しい仕様書を書くと軽蔑されるような会社で働いているのなら、別な働き場所を探すことだ。人生はそんないかめしく惨めな場所で日中を過ごすには短かすぎる。

ルール2: 仕様書を書くのは頭が実行するコードを書くようなもの

私はプログラマが良い仕様書を書くのに苦労する理由をこう考えている。

あなたがコードを書くとき、あなたの主たる読者はコンパイラだ。そう、人々もまたコードを読まなきゃならないのは知っているが、しかしそれは一般にとても難しい。多くのプログラマにとって、コンパイラが読んで正しく解釈できるようにコードを書くだけでも十分難しい。その上コードを人が読めるようにしようというのは贅沢と言うものだ。あなたが

void print_count( FILE* a, char  *  b, int c ){
    fprintf(a, "there are %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "employees", n) /* コードは
わざと分かりにくくしてある */ }

と書こうと、あるいは

printf("there are 10 employees\n");

と書こうと、結果は一緒だ。プログラマがこんな風に書くのはそのためだ:

関数AddressOf(x) はユーザxからそのユーザのRFC-822互換emailアドレスを表すANSI文字列への写像として定義されているものとする。ユーザAとユーザBがいて、AはBにメールを送りたいものとしよう。ユーザAは他のところで定義されている何らかの(しかしすべてのではない)方法を使い、新規のメッセージを初期化し、To:エディットボックスにAddressOf(B)を入力する。

これは以下のように仕様化されていても良かった:

ピギー嬢は昼食に誘おうと、新しいメールを書き始め、"To:"ボックスにKermitのアドレスを入力する。

テクニカルノート:アドレスは標準のインターネットアドレスでなければならない(RFC-822互換)。

両方とも「意味するところ」は理論的には同じで、ただはじめの例は注意深く解読しない限り理解不可能で、2番目の例は簡単に理解できるというだけの違いだ。プログラマはしばしば緻密な学術論文みたいに仕様書を書こうとする。彼らは「正しい」仕様書というものは「テクニカルに(専門的に)」正しくなければならないと考え、そして取り乱すのだ。

あなたが仕様書を書くとき、それは正しいだけでなく、理解可能な必要がある。それはプログラミング用語で言うと、人の頭がコンパイルできるように書かなければならない、と言うことだ。人の脳とコンピュータの大きな違いは、あなたが後で使う用語を定義している間、コンピュータは喜んで辛抱強く待っていると言うことだ。しかし人はあなたがはじめに動機付けしてやらないと、あなたの話していることを理解しようとしない。人は何かを解読したいとは思わず、ただ順に読んでいって理解できることを望んでいる。人に対しては、あたなはビッグピクチャーを提示し、それから詳細を埋める必要がある。コンピュータプログラムは、頭から終いまでずっと、いちばん詳細なレベルのままだ。コンピュータはあなたの変数名に意味があるかどうか気にしない。人の脳というは、たとえ断片的なものであっても、何かストーリーを使って明確な絵を心に描くことができたとき、ものごとをよく理解するのだ。それは私たちの脳がストーリーを理解するように進化してきたからだ。

チェスのゲームの途中のチェスボートを、経験を積んだチェスプレーヤーに1、2秒でも見せると、彼らは即座にすべての駒の配置を記憶できる。しかしあなたが駒をいくつか、通常のゲームではあり得ない仕方で(たとえばポーンを最前列に置くとか、黒のビショップを両方とも黒の升目に置くとか)動かすと、そのボードを記憶するのがずっと難しくなる。これはコンピュータの考え方とは違っている。チェスボートを記憶できるコンピュータプログラムにとって、可能なチェス盤でも不可能なチェス盤でも記憶する難しさは変わらない。人の脳が働く仕方はランダムアクセスではない。脳の中で記憶経路は強化されていくので、より一般的なものは、そうでないものよりも理解しやすい。

だから仕様書を書くときには、あなたがそれを説明している相手を想像し、各ステップであなたが彼らに理解してもらおうと思っているものを想像してみる。その文を読んでいる人は、彼らにすでに話したことをもとに深く理解することができるだろうかと、一文ごとに自問してみること。あなたのターゲットとしている読者の誰かがRFC-822が何か知らないなら、それを定義するか、少なくともテクニカルノートにRFC-822に関する記述を埋め込み、その仕様を読む経営者タイプが、のっけからたくさんの技術用語を見て読むのをあきらめてしまうことのないようにするのだ。

ルール3: できる限り単純に書く

単純な文章で書くのが専門的でないという理由で堅苦しいフォーマルな書き方をしないで、可能な限り単純な言葉を使うこと。

人々は｢use(使う)｣が専門的でないという理由で｢utilize(活用する)｣のような言葉を使う(「専門的でない」がまた出てきた。それは専門的でないのでそうすべきじゃないと誰かが言うときはいつも、彼らが本当の議論にネタ切れしているのだとわかる)。実際、多くの人は明快に文章を書くと、何か間違っているように思うようだ。

たくさんのスクリーンショットを使う以上に仕様書を改善する方法はない。一枚の絵は何千の言葉にも勝る。Windowsのソフトウェアの仕様を書く者は誰でも、Visual Basicを買い、少なくともスクリーンのモックアップが作れるくらいには使えるようになるべきだ。(MacならREAL Basicがある。WebページにはFront PageかDreamweaverがいい)。それからそのスクリーンショットをキャプチャして(Ctrl+PrtSc)、仕様書に貼り付けるのだ。

ルール4: 何度も見直し、読み返す

えーっと、私ははじめ、このルールについて長い解説を書くつもりでいたが、しかしこのルールはあまりにシンプルで自明だ。あなたの仕様書を何度も見直し、読み返すのだ。いい? もし超簡単じゃない文章を見つけたら、それを書き直すこと。

ルール4の説明をしなくて時間が余ったので、もうひとつルールを追加することにしよう。

ルール5: テンプレートは有害と思われる

仕様書の標準テンプレートを作りたいという誘惑を避けること。はじめあなたは｢すべての仕様書が同じように見える｣ことが重要と思うかもしれない。ヒント: そうじゃない。どんな違いがあるか? あなたの家の本棚の本はみんな同じように見えるだろうか? そのほうが望ましいと思う?

さらに悪いことに、テンプレートを持っていると起こりがちなのは、重要そうに思える機能のためにたくさんのセクションをテンプレートに追加するということだ。例: ビッグ･ビルは今後すべてのMicrosquish製品にインターネット・コンポーネント入れることを命ずる。そうすると仕様書テンプレートは、今や「インターネット・コンポーネント」というセクションを持つようになる。誰かが仕様書を書くときにはいつも、いかに自明であっても、「インターネット・コンポーネント」が何かというセクションを埋めなければならない、たとえ彼らがただMicrosquishキーボードの仕様書を作っている場合でもだ。(なぜあの役に立たないインターネット･ショッピング･ボタンがキーボードの上にキノコみたいに生えるようになったのか不思議に思っていたことだろう。)

このようなセクションが積み重なっていくと、テンプレートは非常に大きくなる。(ここにとてもまずい仕様書テンプレートの例がある。誰がいったい仕様書に参考文献を必要とするのだろう? あるいは用語集を?) このような大きなテンプレートの問題は、それが圧倒されるように見えるために、人々を仕様書を書くことから追い払ってしまうということだ。

仕様書はあなたが人々に読んでもらいたいと思うドキュメントだ。その意味ではニューヨーカーのエッセイや大学の論文と同じだ。論文を書くためのテンプレートを学生に配る教授の話を聞いたことがあるだろうか? 1つのテンプレートに合っている2つの良いエッセイというのを読んだことがあるだろうか? そんな考えはただ捨てることだ。