【読書】システム設計とドキュメント

はじめに

システム開発において、技術的スキルやプログラミング力は重要ですが、開発を成功に導くために忘れてはいけないのが設計書やドキュメントの作成力です。これらは単に開発を効率化するだけでなく、プロジェクトの進行をスムーズにし、保守・運用段階でのトラブルを防ぐための土台にもなります。
『エンジニアなら知っておきたい システム設計とドキュメント』は、システム設計の基礎やドキュメントの作成方法について体系的に学べる一冊です。
本記事ではそんな本書の内容の一部をまとめてみました。

• エンジニアなら知っておきたい システム設計とドキュメント

プロジェクトを成功させるには？

プロジェクトの成功率は上がっている

令和時代の今において、最近のプロジェクト成功率は上がっていると言います。その主な理由は「プロジェクトの定量管理」が定着してきたからです。定量管理とは、WBSにおいて進捗率を数値化したり、数値データを用いた実績との比較に基づいた目標設定や見積もりを行うことです。

プロジェクトの失敗原因

• システム仕様変更が相次いだ
• 各フェーズの見積もりが甘かった
• システムの不具合など想定外の問題が発生した
• エンドユーザーの協力が得られなかった

プロジェクト失敗を防ぐ３つのノウハウ

工程QA

QAとはQuality Assurance「品質保証」です。
各工程のアウトプットに問題がないかを確かめます。

見積もり審査会

見積もりをお客さんに提出する前に、審査会というものを内部で行います。さまざまな観点からなるチェック項目表（体制、スケジュール、コスト、技術）を見積もり担当者とPMで作成します。そしてその内容を第三者の目線からその見積もりが妥当かどうかを複数人の審査会で評価します。

リスク標準

プロジェクトがスタートしたときにリスクを洗い出して、それらを減らしたり回避するための対策とモニタリングを行います。

良い設計書を作るには？

設計書を作成する３つの目的

完成イメージを共有する

顧客から要件を聞いてベンダーが作るシステムをイメージできたとしても、それが顧客の求めるものだとは限りません。さらに、共有する相手はお客さんだけではありません。規模が大きいプロジェクトほどメンバーの入れ替わりは激しいため、様々な人間が呼んでも同じイメージを共有できるような設計書である必要があります。

プログラマーへの仕様指示

ここをクリックしときにどのようなイベント（APIが呼び出される、モーダルが開くなど）が発生するのかというロジックをプログラマーに伝えます。基本設計では主に顧客に対してイメージを共有することがメインですが、詳細設計ではプログラマーが必要とする情報を載せる必要があります。

保守・運用の負担を軽減する

開発したシステムを開発した人間が保守・運用するとは限りません。むしろ、違う人間であることの方が多いです。また同じ人間であったとしても、1、2年も前に設計したものであれば同じ人間でも仕様を覚えていません。障害が発生した時、仕様の変更追加を行う場合に、設計書はソースコードを解析する手間を省いてくれます。

良い設計をするために、リーダーがすべきこと

個々の設計書の標準化をする

もし設計書が標準化されていなければ設計者は「どのような設計書が良いのか」を考えながら使用を考える必要があります。さらに保守・運用の際もバラバラの書き方であると読み解くのも大変になります。標準化は設計作業を効率化し、読み手の負担を下げる効果があります。

設計者全員に設計書の記述方法をレクチャーする

標準化によって決めたルールをメンバーに従ってもらわなければ意味がありません。そのためにはメンバーがそのルールの意味や目的を理解しておく必要があります。設計書の記述方法のレクチャー会を開いたり、設計書の作成中であっても定期的に質問をメンバーから集めてそれに回答する会を開くような運用があると良いです。

システム開発全体の標準化をする

広い目で見た時に標準化すべきなのは設計書だけではありません。WBSの標準やテスト仕様の標準など、いろいろなドキュメントが存在します。これらの資料を目的別に整理すると、「プロセスの標準化」と「ドキュメント（成果物）の標準化」に分けられます。「プロセスの標準化」に該当するのはWBSの標準や見積もり標準など、プロジェクト管理に関するものです。
一方「ドキュメントの標準化」では設計書やテスト仕様書、コーディング規約などが当てはまります

良い設計をするために、メンバーがすべきこと

必要最低限なことをシンプルに書く

基本設計はユーザーが完成をイメージを共有することが主な目的ですが、詳細設計はプログラマーへの細かな仕様指示をするために行うことが多いです。その際に注意すべきことはプログラマーの裁量に任せるべきところは書かないです。余計な記述は仕様の誤解を招き、厚い設計書は読み手の読む気を奪います。

One Fact One Place

One Fact One Placeとは１つの事実を示すデータは１つの場所だけにしか存在させないという意味です。複数箇所（ページやシートごと）に同じことを示すデータがあると、変更する際に手間が発生します。さらにその際に変更漏れをしてしまった場合、矛盾を生んでしまいます。項目定義書の変更をしたら画面のレイアウトも自動で変わる、ような仕組みは積極的に取り入れるべきです。

概要説明の記述に手を抜かない

設計書を読む最初に概要や役割を理解した上で読む方がその後の理解が進みます。その設計書を読むすべての人間が理解できる内容を書くことを心がける必要があります。どのくらいの粒度で書くべきかはプロジェクトやその設計書の目的によって異なるため、全体で概要の書き方をレクチャーするような運用があると良いです。

変更履歴には簡潔に正確な内容を書く

どこの何が変わったのかを一目でわかるようにします。例えば「〇〇を変更」と書くのではなく「〇〇の××を△△に変更」と言ったようにどこの、何を、どう変えたのか、がわかるように書きます。さらにその変更を行なった背景や理由があると良いですが、それらを含めると記述量が多くなってしまうので、チケットなどにまとめておいてそのリンクを変更履歴の横に書くような運用が良いです。