はじめに
本記事はリンクアンドモチベーション Advent Calendar 2023の1日目になります。
今年から上流工程に関わることが増えたため、たくさんのドキュメントを書きました。
「書く技術：レベル1」だった私は、たくさんボコボコにされました...
ここでは私がレベル上げをしていく過程で、特に経験値をもらえた3つの学びを紹介します。
レビュワーと後工程の担当者が理解できる内容にする
以下の問いを立ててみましょう。
- あなたのドキュメントの読み手は誰ですか？
- その人とあなたでは前提情報にどんな差がありますか？
以下は読み手ごとの理解度の違いの一例です。
| 読み手 | 理解している情報 | 理解していない情報 |
|---|---|---|
| レビュワー | プロジェクトの長期的な目標、ビジネス上の優先順位 | プロジェクトの全体像、既存機能の設計、コードの機能性 |
| 開発者 | 技術的な詳細、コードの機能性 | プロジェクトの目的、背景、歴史 |
| 保守者 | システムの運用方法、保守のプロセス | プロジェクトの目的、背景、歴史 |
ドキュメントの前提となる情報は、自分にとっては明らかな内容でも、レビュワーや後工程の担当者にとっては未知のものかもしれません（前提質問の嵐が起きてしまうかも）。
何を理解していて、何を理解していないのかを整理した上で、前提情報を記載しましょう。
世の中の当たり前に忠実に作る
私の祖父が自転車を「けった」と呼んでも伝わらないように、世間一般と異なる表現は、ドキュメントにおいて理解を妨げます。
ドキュメントで使用する言葉や図は、読み手が理解できる「当たり前」のものであるべきです。
例: アクティビティ図の誤解
私は以前、アクティビティ図において、長方形をデータストアとオブジェクトだけでなく、アクションを表すのにも使用していました。これは、UMLの標準的な使い方に反していたため、読み手に混乱を与えてしまいました。
ドキュメントが、読み手の「当たり前」から外れないように、標準を知り準拠しましょう。
プロジェクトの全体像からドキュメントの位置を構造化する
以前、上司からこんなコメントをもらいました。
「プロジェクト全体から見て、このドキュメントがどの位置に当たるか、どこと対応しているかわからないよ」
当たり前ですが、レビュワーは書いてあることからしか情報を読み取れませんので、どのような構造になっているかを明確に表しましょう。
例：あるウェブアプリケーション開発プロジェクト
例えば、以下のようにプロジェクトで必要なアウトプットを構造化してみましょう。
- 要求定義書
- 全体
- 要件定義書
- 全体
- コンポーネントA
- コンポーネントB
- 設計書
- 全体
- コンポーネントA
- コンポーネントB
- テスト仕様書
- 全体
- コンポーネントA
- コンポーネントB
1つのドキュメントの中身は、役割と関連が明確になるように書くことによって読み手に優しくなります。
- 設計書
- 全体 ・・
- コンポーネントA
- メッセージ
- この設計書では〇〇という要件を実現するためのAPI設計を記載する
- メッセージの補足材料
- アーキテクチャ
- インターフェイス仕様
- データ構造
コンポーネントAの設計書を読んでいるときに、その役割とどの要件に対応するのかが明示的になりましたね。
全体像から見て、そのドキュメントがどのパーツなのかわかるように構造化されたドキュメントを記述しましょう。
終わりに
技術を実現するだけでなく、それを適切に伝えるスキルも同様に重要だと思いました。
今後もどんどん書いて「書く技術：レベル100」を目指そうと思います。