IT古典良書を読み解く《第3回》やさしい機能仕様 後編
第3回 Joel on Software(ジョエル オン ソフトウェア) －その3－ 「やさしい機能仕様 後編」
こんにちは。スクラムマスターの伊藤です。
こちらは「やさしい機能仕様 後編」になります。誰が殺されたかも知らないのに犯人はお前だ！的な話が始まってしまうので、前編から読むことをオススメします。
だけど…どうやって書くの？
仕様書の必要性、書かないことのデメリット、書くべき仕様書（機能仕様書）についても、分かりましたね。「じゃあ、書きましょう」といっても書けないのが人間です。
重要で、かつ見落としがちなことを先にひとつ、仕様書を書かない理由で、「仕様書は生きている必要がある」ということです。
誰も読まないという話がありましたが、狭義のシステムエンジニアがプログラム設計書を書いて、プログラマに丸投げして、プログラマが「なんだ？ この落書きは」と思いながらコーディングをしているプロジェクトもまだあるかも知れません。
これも、仕様書が酷い評判を受けている理由ですが、更に「仕様書は役に立たないよ。誰も従わないんだから、陳腐化していて、決して製品を反映していないんだ」となりますがジョエル曰く、あなたの仕様書は陳腐化して製品を反映していないかもしれないが、私の仕様書はいつもアップデートされている。仕様書はコードコンプリートしたときに初めて凍結されると、ちなみに更新した際はリビジョンマークを付けておき、更新されたところだけ目を通せばいいようにしているようです。
ウォータフォールはどうするんだという話ですが、ウォータフォールならば途中でアサリ蒸し器が追加されるわけないのにおかしいですねぇ。
では、書き方の紹介に入りましょう。まず機能仕様書に必要な項目です。
● 注意書
純粋に自己防衛のために、「この仕様書は未完成である」みたいな一文を追加しておきましょう。
● 作成者
チームによって書かれるべきという考え方もあるが、仕様書は規模が大きい場合は分割し、一人の人間に割り当てて、責任と所有権を持つべきとのこと。
● シナリオ
これは日本でやるにはペルソナを設定しての製品利用想定シナリオとでも書かないと怒られそうですが、人々がその製品をどのように使うかについて、現実的で生き生きとしたシナリオが必要。
● 対象外
やらないであろうこと。サポートしない機能などを記述。
● 概要
仕様書の目次のようなもの、全体像を把握するもの、簡単なフローチャートかもしれません。
● 詳細、詳細、詳細
そして、詳細。仮にWebアプリを作るのであれば全ての画面に正式名称を付け、振る舞いや異常系の動作について詳細を記載。
● 未解決の問題
最初のバージョンで議論すべき未解決の問題があるのは構わないとのこと。コーディングに取り掛かるまでには解決する必要があります、検索しやすいようにしておきましょう。
● ノート
仕様書を読んでいる特定の読者層に向けてのノート。例えば、コーディングに有益な情報はテクニカルノート、テストケース作成に役立つ情報はテスティングノートといった形で記載。
《よもやま話》
Joel on Software P73 にはソフトウェアマネジメントの古典である『人月の神話』（1975年！ 原題: The Mythical Man-Month: Essays on Software Engineering）について触れています。この本の要点は、遅れているプロジェクトでプログラマを増員すると、プロジェクトは余計に遅れるということです。その理由は、チームにn人プログラマがいるとき、コミュニケーションパスの数はn(n-1)/2になりますが、これはO(n2)で増加するからです。まぁ、分かりやすくいうと、コーディングは単純作業じゃないんです。
仕様書を人に読んでもらうための、５つの簡単なルール
1. 可笑しくすること
1番目は、読むのが楽しくなるようにすること。しかしながら日本では難しいかもしれません。口頭でジョークを言うには寛容な国（？）ですが、文章にジョークを書くのは不寛容な国で、難しくカタカナを使ったほうが喜ばれれます。ロックダウンがオーバーシュートしてクラスターなんですと書くのも可笑しいですが、シナリオだけでも頑張ってみましょう。
2. 仕様書を書くのは頭が実行するコードを書くようなもの
コード（仕様書）が正しいかどうかだけではなく、コンパイラ（読者）が理解できるかどうかを意識して書きます。そうしないと、難解で前提知識がないと何回読んでも意味がわからない仕様書が出来上がり誰も読んでくれません。
3. できる限り分かりやすく書く
英語でもuseよりutilizeを使ったほうがフォーマルとかプロフェッショナルという話があるそうですが、分かりやすくとは以下のようなことを行います。
- できる限り簡単な言葉を使う
- 短い文に分割する
- ページが文字で埋められて、文字の壁になることを避けること
- 箇条書き、挿絵、チャート、表、空白を使うこと
- スクリーンショット特に画面のモックアップを貼ること
4. 何度も見直し、読み返す
はい。読み直しましょう。そして、簡単では無い文章を見つけたら修正しましょう。
5. テンプレートは有害である
この項目は難しいところですが、適当にテンプレートを拾って開くと、無駄なセクションが大量にあり、これを全て作成するのかと怖気づいてしまうところが有害です。参考にしてもいいかもしれないですが、必要な項目のみ書くようにしましょう。
そして、最後に誰が書くのか？
これについても種々書かれているのですが、Microsoftは開発が大規模になってきたときにプログラムマネージャー（プロジェクトやプロダクトではない）を置き、彼に書かせるようしたそうです。プログラムマネージャー1人に通常5人のプログラマがいて彼らは仕様書の内容を実装する責任があり、プログラムマネージャーはプログラマが時間を費やすべきでないあらゆる煩わしい詳細に関して調整を行う必要があると。このポジションが設置出来れば開発現場はうまくまわりそうですが（スクラムマスターみたいですね）、現実的には難しくプロジェクトマネージャーかプログラマが書くことが多そうです。
ひとつ言えることは、ドキュメント作成が得意でないプログラマに無理に書かせるのでなく以下のようなスキルを持った方に書かせるほうがうまくいくということです。
● 明快な文章が書けること
● 外交手腕
● マーケットに対する意識
● ユーザーに対する理解
● 良いUIデザインの能力
ジョエルが書いた機能仕様書のサンプルURLを再掲しておきます。
- Sample https://www.joelonsoftware.com/whattimeisit/
- Sample https://bit.ly/2zWg2Xw （日本語アーカイブ）
話は急に変わりますが、弊社は品質保証の会社として、仕様書がないソフトウェアの試験も賢明に行ってきた実績があります。仕様書がなくても臆せずご相談ください。（あぁ、QAチームの皆様 本当にごめんなさい。）https://info.shiftinc.jp/service_contact
《よもやま話》
知る人ぞ知る、昔放送していたNHKのコント番組「サラリーマンNEO」の中でサラリーマン語講座というコーナーがあり、普通にためになりました。上司にたくさん仕事をふられ、「どれを優先したら良いんですか」と聞くと「それを考えるのがお前の仕事だろ」と怒られる寸劇の後に講師の方が、このマジカルワードを使いましょうと出てくるのが「ファースト・プライオリティ」。不思議なことに「ファースト・プライオリティはどれでしょうか」と聞くと上司は答えてくれます。他にも「同じこと考えていました」「正直ベースで」「ASAP」といった本当に使える（使われる）言葉を教えてくれていました。
――――――――――――――――――――――――――――――――――
執筆者プロフィール：伊藤慶紀
大手SIerにて業務用アプリケーションの開発に従事。
ウォーターフォールは何故炎上するのか疑問を感じ、アジャイルに目覚め、
一時期、休職してアメリカに語学留学。
Facebookの勢いを目の当たりにしたのち、帰国後、クラウド関連のサービス・プロダクト企画・立ち上げを行う。
その後、ベンチャーに転職し、個人向けアプリ・WebサービスのPM、社内システム刷新など様々なプロジェクト経験を経てSHIFTに入社。
趣味は将棋、ドライブ、ラーメン、読書など
お問合せはお気軽に
https://service.shiftinc.jp/contact/
SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/
SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/
SHIFTの導入事例
https://service.shiftinc.jp/case/
お役立ち資料はこちら
https://service.shiftinc.jp/resources/
SHIFTの採用情報はこちら
https://recruit.shiftinc.jp/career/