ドキュメントはエンジニアを助けるもの

コードをいじっているのが大好きな人は結構多いのではないでしょうか。

多くの学生たちにとって「モノを作る」ことがしたくてこの業界の門戸を叩いたのであれば当然かもしれません。あるいはそういう先達たちの手によって新人教育時代から延々とプログラミングばかり教わってきた人たちにとってはそうなのでしょう。

かくいう私自身も新人の頃はそういう側面もあったと思います。

新しいプロジェクトを始めるとき、ざっくりと要求を理解した段階でいきなりコードを書いてしまう人が少なからず存在します。ひどい場合には「何もまだ思いつかないけど、取りあえず起動画面だけ作ってみるか」という人もいました。

その後、彼が何をするかといえば最初に書いたコードに少しずつ機能を付け加えていくのです。そうしてコードを膨らませていけば、いずれはシステムが完成するだろうというわけです。

作業が進むにつれていろいろな設計上の問題や仕様の矛盾が出てきますが、それはその場その場で考えてやり過ごそうとします。あるいは「この要件には矛盾がある！ こんなの作れない」といって怒り出すかもしれません（最初によく考えずに作業を始めた自分のことを棚に上げていることに気付く人は少ないようです）。

全体を見通して考慮しなければならない問題に対しては、お手上げになることさえあります。お客さまのニーズを完全に無視してしまってさっさと作り始めた機能や処理との整合性ばかり語る人も少なくありません。

また、このようにして膨らませただけのコードも、簡単に捨て去ることができなくなっていることが多いことでしょう。プロジェクトの開始からそれなりの時間が経っていれば時間的にも心情的にも、もう後戻りできないからです。

 このような"場当たり的"なプログラミングが、非常にリスキーなのは明白です。実際、そうした進め方を許容したせいで何十億という赤字に発展したプロジェクトも知っています。というか何日も何十日も帰れない日を経験しながら解決に勤しみました。　

場当たり的開発は時間の浪費

 機能仕様書では、自然言語で仕様の要点を書いていきます。

たとえば、スマートフォン用にカメラを使ったアプリケーションを開発しているとしましょう。以下のような仕様を記述したとします。

カメラを起動してユーザーに写真を撮影してもらう。
撮影したらその画像を左右反転し、横1024ピクセルに縮小してからファイルに保存する。

実際、この仕様を書くのにほんの1分もかかりません。

これを見たユーザーから「撮影した横幅が1024ピクセル未満の時はどうするのか」といったような指摘を受けたとしても、修正するのは数分程度でしょう。

カメラを起動してユーザーに写真を撮影してもらう。
撮影したらその画像を左右反転し、横1024ピクセルに縮小してからファイルに保存する。
ただし、オリジナルの画像の横幅が1024ポクセル未満の場合は警告メッセージを出力し、もう一度カメラに戻して1024ピクセル以上の画像をユーザーに撮影してもらうようにする。

逆に、もしこのような仕様書を作らずに「ベータ版」のアプリを作ってしまったとしたら、最初のバージョンを作るのに数日はかかるでしょう。

そして「ベータ版」を見たユーザーから上記のような指摘を受け、そこからプログラムの修正に入ると画面遷移の変更に１日かかることが判明したとします。そうなればさらに他の機能やデータ構造の変更などの兼ね合いから、追加の修正作業やテストに数日必要になりそうです。

結果的に、最初に機能仕様書を書いていれば数分で終わったはずの作業に数日を要してしまいます。これは完全に時間の無駄使いです。

仕事のパフォーマンス…生産性を阻害する要因は突き詰めてしまえばそれほど多くありません。

　・考える／悩むなどの時間がながい
　・準備できていない
　・単純に作業効率が悪い
　・ミスや漏れによる手戻り
　・コミュニケーション不良による手戻り

たったこれだけです。効率を上げることを私はわかりやすいように『楽をする』と表現していますが、楽をするのはいいんです。企業としても結果的に生産性が上がるのであれば楽をしようと努力する姿勢はむしろ推奨すべきことでしょう。

ですが『楽をする』前提として品質を下げていては意味がありません。

品質を下げるような取り組みを私は『手を抜く』と呼んでいます。その名の通り、必要不可欠であるはずの「手（順）を抜く」のですから、想定していた結果と異なるのは当然です。

たとえば料理のレシピなどでたった１つでも手順を抜いたらレシピ通りの料理が出来上がるでしょうか？

手を抜けば想定通りの結果にならないことなど子供でも理解できる道理です。今回の例では、設計書なり仕様書を作成し、認識齟齬が起きていないことをしっかり確認するという手順を抜いたわけです。

仕様書によって正しい設計に速く到達できる

前述のように、仕様書や設計書を作成するメリットは設計に要する時間の節約です。この作業そのものを無駄と感じている人にとっては節約にすらなっていないかもしれませんが、仕様書に書けばそれぞれの機能はほんの数行の日本語となり、誰が読んでも理解できるものとなります。

もちろん修正も簡単です。

日本語では数行で表現できたものが、いきなりプログラムコードを書いてしまうとその何倍も時間がかかります。しかもプログラムを理解できる人にしか理解できませんし、修正もはるかに困難です。

また、仕様書なら日本語さえ読めれば多くの人が確認できますし、そのぶん問題点を早期に発見できます。

それに、そもそも要求を正しく理解していなければ仕様が書けないわけですから、プログラマーやエンジニア自身の理解度を試す良いテストになります。

そして、ユーザーを含めた多くの人にレビューを受けることができ、間違いや不足点を速く洗い出せます。

仕様書によって未決定事項がはっきりする

 たいていのシステムにはユーザーの間でも意見が割れる"デリケートな"機能が１つや２つはあります。 

その仕様はなかなか決まらず、何回ミーティングしてもペンディングのままになることも多いでしょう。ドキュメントを軽視するチームが開発すると、この種の問題は途中でうやむやになることがしばしばあります。

そして、納期直前になって「そういえば、あの件はどうなった」という指摘を受けて大問題になるのです。

仕様書に慣れているチームならば、このような問題は未然に防げます。

仕様書に「この仕様は未定である（TBD：To Be Determined）」という印を付けて記載できるからです。仕様書は決定事項を書くためだけのものではなく、未決事項や検討中の事項も記載して構わないという点において、とても優れたドキュメントなのです。

また仕様書は一度書いてしまえば、どんなに多くの人と共有してもコストは同じです。ユーザーもテストチームも、サポートチームも営業も同じように確認することができ、同じ出発点に立ってシステムを理解できるようになります。

後からチームに加わった人にゼロから同じ話をする必要もなくなります。もしもプログラムコードを作成した担当が病気で離脱したり、離職してしまったら誰が過去からの経緯を含め、責任をもって担当できるのでしょう。

また、設計者自身も何度も何度も読み返して確認できます。

もし仕様書がなかったとしら、悲惨な状態になるでしょう。ほかの開発メンバーはもとより、テストやサポートのチームからも何か仕様に疑問が生じるたびに開発チームに質問が飛んできます。それも同じような質問が何度も何度も来ます。そのたびに開発作業に割り込みが生じ、一番貴重な開発チームの生産性が下がっていきます。これは表面的には目に見えにくいポイントですが、実際には大きなコストとしてのし掛かってくるでしょう。

プロジェクト計画にあたって自分たちがどんなシステムを開発すればいいのか、これが正確に理解できていなければスケジュールも正確に見積もれません。

　仕様書によって機能が明確になってこそ、
　正確に作業項目を洗い出すことができ、
　正確なスケジュール作成につながる

のです。

よく「自分はそんなことない」と言う人がいますが、そう言う人は胸に手を当ててよく問いかけてみましょう。 

「その"そんなことない"は、本当にプロジェクトメンバー全員が共有できる回答なのか？『自分だけ』そんなことない状況でプロジェクトは成功できるのか？その責任をとれるのか？」

と。それができなければチームワーク、ひいては集団活動そのものに向いていないと言わざるを得ません。

結局、経験則を持つ限られたメンバーのみの主観でしかなければそれは超属人的、超自己中心的なものであって、チーム全体または組織全体で共有できる意見ではありません。

いずれ自分が部下にスケジューリングを指示した時のことを考えてみてください。自分ができていれば他人もできて当然のはず、と言うのはただの横暴なのです。