残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門：プロジェクト成功確率向上の近道とは？（3）（1/3 ページ）

ITシステム開発の問題点の一つであるコミュニケーションの失敗。本連載では、これを防ぐ方法としてお勧めしたい3つのドキュメントを紹介していく。今回は、「技術視点」のドキュメントとして、2000年代以降注目されている「Design Doc」について解説します。

[寺田英雄，株式会社オープンストリーム CTO]

　IT技術がビジネスに貢献していくためには、まずはシステム開発を成功させることが重要です。本連載「プロジェクト成功確率向上の近道とは？」では、システム開発を成功させるために、コミュニケーションが果たす役割の重要性と、ドキュメントによるコミュニケーションの重要性について解説してきました。

　連載1回の「ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門」、第2回の「サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック」では、「ユーザー視点」で要求仕様を表現する「Joelの機能仕様書」について説明しました。第3回目となる今回は、「技術視点」のドキュメントとして、2000年代以降注目されている「Design Doc」について解説します。

　なお、主に想定している読者は、「プログラミング経験はある程度あるが、設計書をあまり書いたことのない初級〜中級のエンジニア」です。

Design Docとは、どんなものか？

　Design Docは、グーグルに代表される最先端の技術企業で取り入れられている設計ドキュメントのスタイルです。単にドキュメントの書式だけを指すのではなく、書いた後の使い方までを含めた『開発のやり方』につながっているドキュメント方式です。アジャイルなどの現代的なソフトウェア開発スタイルにフィットしているため、シリコンバレーのスタートアップ企業などで広く受け入れられているようですが、筆者の実感としては日本ではいまひとつ普及していないように思えます。

　Design Docは、エンジニアがこれから開発しようとするソフトウェア設計の基本的な要点――何を（What）・何のために（Why）・どのように（How）作るのか？――を説明するために書くドキュメントです。要点だけを書いて、それ以上詳細なことは『書き過ぎない』ことが重要です。現代の開発スタイルでは、詳細な情報を得るには『ソースコードを見た方が早い』からです。

　Design Docには、誰でも読める自然言語（日本語や英語）の文章で書くことが必要です。図やチャートを使ってもよいですが、それらは文章を補助するものという位置付けです。読者の皆さんも経験があると思いますが、図やイラストだけの資料だと、しばらく時間がたってから見ると正確な意味が分からなくなってしまうことがあります。情報の正確さや再現性の高さでは文章が一番です。

「思考の道具」としても役立つドキュメント

　Design Docの最初の読者は設計者自身です。他のドキュメントと同様に関係者に公開して情報共有に使う役割もありますが、設計しているエンジニア自身の「思考の道具」としても価値が大きいものです。

　システム設計は時間のかかる複雑な作業です。関連するさまざまな要素について検討し、課題を解決し、それぞれの仕様を決定していかなければなりません。人間の脳は、そうした複雑な問題全体を一度に考察するのは苦手ですので、何らかの形で分解して、途中経過を記録しながら作業を行う必要があります。

　そのための手段としてもDesign Docはうってつけです。Design Docは常に変化し、生きているドキュメントです。試行錯誤の途中のアイデアでもよいので、どんどん書き出してみて、何度も修正しながら仕上げることができます。

今どきの開発スタイルに適合する

　アジャイル方式などの繰り返し型開発や、メンバー全員が1カ所に集まらない分散型のチーム運営など、今どきの開発スタイルを使うチームに導入してもDesign Docは効果を発揮します。

Design Docの実例を見てみる

　具体的なDesign Docの実例を見てみましょう。日本語でDesign Docを公開されている事例が少ないため、英語版のものを引用してみます。英語が苦手な人も、項目タイトルだけ辞書で意味を確認してみれば雰囲気が分かると思います。

1. WebKit WebSocketDesign Doc（グーグル）
2. The Chromium Projects - Extensions

典型的な記述項目

　実例を見ると分かるように、Design Docに決まったフォーマットはありませんが、記述される項目はだいたい似ており、およそ下表に示すようなものとなっています。

表　Design Docに含み得る項目一覧

	項目名	内容
1	＊タイトル	このソフトウェアの名称
2	＊著者名	このDocを書いた人
3	プロジェクトメンバー	開発に参加するメンバー
4	＊目的	このソフトウェアの目的
5	要求仕様	要求仕様書、機能仕様書などへのリンク（要求仕様の要点を書く場合もある）
6	＊背景	このソフトウェアを開発する背景・経緯など
7	既存のものとの相違点	既存品があるなら、それとの違いを書く
8	関連システム・仕様など	関連システムやその仕様書へのリンク
9	＊ハイレベルアーキテクチャ（アーキテクチャ概要）	システム全体を俯瞰した構成図など
10	＊各パート（モジュール・クラス）の概要	各パートの概要・責務・目的など
11	＊各パート（モジュール・クラス）の内部仕様・処理フローなど	データ構造、アルゴリズムなど
12	各パート（モジュール・クラス）の実装場所	ソース・ファイル名、実行形式の名称など
13	使用例	モジュールの利用例が分かるサンプルコードなど
14	セキュリティ仕様・考慮事項など	想定される問題と、その対処方法などについて
15	既知の問題	事前に判明している問題・課題などを書く
16	＊テスト方案	どういう観点で何をテストすればよいか、どのようにテストすればよいか
17	運用方法	運用時のポイント、監視の方法など
18	参考文献	参考文献へのリンク
19	このDocの格納場所	リポジトリのパス、ファイルサーバのパスなど
20	メモ	設計のヒントや気付いた点、関連情報など何でも
21	変更履歴	このDocについて、いつ・誰が・どのような変更をしたのか履歴を記述

　これらの項目のどれを含むかどうかは作者の任意です。自分のプロジェクトの目的に応じて書くべき項目を選びましょう。ただし、この表中の項目名に（＊：アスタリスク）が付いているものは、ほぼ必須と考えてよい項目です。

　ここからは、筆者がよく実施している作業ステップに沿ってDesign Docの書き方を紹介します。このやり方が全てではありませんので、読者は自分の状況に応じて効果的なやり方に修正してみてください。

Design Docを書く事前準備

　Design Docをいきなり書き始めることができるケースはなかなかありません。通常は事前に準備作業が必要です。それは、『要求仕様の理解』と『要素技術や開発環境の理解』です。事前準備と設計の関係をまとめたものを図1に示します。

図1　Design Docを書くための事前の準備

要求仕様をよく理解する

　ソフトウェア設計のゴールは「要求仕様を達成する方法を明確にする」ことなので、まずは要件定義書や機能仕様書などを熟読して、要求仕様をしっかりと理解しましょう。書類だけでは不十分な場合には、関係者とミーティングを行って確認することもあります。あらゆる手段を使って粘り強く理解を深めることが大切です。ここで要求を深く理解しておけば、この後の設計で手戻りが減って楽に作業を進めることができます。

　集めた情報はしっかりとメモしておきましょう。ここで先にDesign Docのひな型を作って、そこにメモを残すという手もあります。

要素技術について確認する

　次に、要求を実現するための手段についての確認です。今回の開発で初めて使う技術や手法・アルゴリズムなどがある場合に実施します。ドキュメントや解説書・サンプルコードなどを読んで求めているものが満たされるかどうか確認します。

　手慣れた手法だけで実施する場合はこのフェーズは省略してもいいでしょう。