ドキュメントを書くために設計書を作る
私はドキュメントを書く前に、設計書を書いて書く内容をまとめています。
設計書、開発の時には必須で作成しますが、ドキュメントも同様であった方が色々と便利なのではと思ったのが発端です。
設計書を作成することの利点としてはいくつかありますが、大きくは下記2つだと思っています。
ドキュメントの目的を把握しやすくなる
他のメンバーにタスクをパスしても、文脈が理解できるようになる
ドキュメントはできれば少ない方が読む方の負担は減ります。そのため、無駄なドキュメントは極力作らない方が良いでしょう。設計の時点で、ドキュメントの目的を見直すことで、本当に必要なドキュメントなのかを判断することができます。
また、ドキュメントは最後まで書き切ることが一番難しいです。どうしても書ききれなくなった場合、必要なドキュメントは他のメンバーにパスして続きを書いてもらうことがあります。その際に、設計書があることでスムーズな引き継ぎが可能となります。
それでは、実際にどのように書いているのかを説明します。
設計書の構成
構成としては、最低限下記を書いています。
・タイトル
・なぜ必要か
・新規追加/既存の修正のどちらか
・概要
・完了条件
・その他添付資料
それぞれ説明します。
タイトル
設計書のタイトルをつけます。
タイトルは分かりやすく動詞を使って記載する必要があります。読み手がタイトルだけで何をすべきなのかを理解できるようにすることが大切です。
読む側の手間を省く努力が必要です。
🙅♀️悪い例
問い合わせがきた内容をドキュメントに追加
🙆♀️良い例
お問い合わせフォームを作る手順をチュートリアルに記載する
なぜ必要か
このドキュメントがなぜ必要かを記載します。
ドキュメントは書こうと思えば無限に書けるのですが、無駄なドキュメントはなるべく書かない方が望ましいです。
そのために、「なぜ」の部分を明確に言語化し、ドキュメントの必要性を判断します。この部分の認識が甘い場合、もう少しチームで議論したり、そおそもドキュメント自体書かないという動きになるかもしれません。
🙅♀️悪い例
・なんとなく分かりづらい気がするので修正
🙆♀️良い例
・お客様から同様の問い合わせが今月だけで10件発生した。ドキュメントを作成することでお客様の負担はもちろん、社内のサポート工数も減らすことができる可能性がある
・現在のドキュメントに誤りを確認した。正確な情報を提供するためにドキュメントを更新する必要がある
新規追加/既存の修正のどちらか
ドキュメント作成において、新規に作成するドキュメントか、既存のドキュメントを修正するものなのかを記載します。
この作業は、単純にドキュメントの重複を防ぐためです。
概要
概要にはドキュメントの内容を詳細に記載します。
新規ドキュメントの場合はドキュメントの構成や、手順が必要な場合は手順も箇条書きで書くとわかりやすいです。
既存の修正の場合は、修正箇所を明確に記載する必要があります。
🙆♀️良い例
システムログイン方法を手順・画像を交えて記載する。手順は以下の通り
1. ログイン画面に遷移
2. ログインフォームに情報記載
3. ログインボタンクリックする
4. エラーが出た場合の対応方法
完了条件
ドキュメントの完了条件を記載します。どこまで対応すればドキュメントリリースして良いよ、という条件を書きます。
🙆♀️良い例
下記が完了したらリリースとする。
☑︎ ドキュメント通りの対応でXXXの設定が完成すること
☑︎ 英訳まで対応できていること
☑︎ サポートチームのレビューが完了していること
☑︎ 開発チームのレビューが完了していること
その他添付資料
伝えておくべきことや、補足資料があれば記載します。
例
・実際にお客様よりいただいた内容をお送りします（やりとりのリンクを送る/添付する）
・ 参考資料を添付しましたので、こちらをドキュメントよりダウンロードできるようにしてください。
まとめ
以上です。設計書は作成に時間がかかってしまいますが、その分とても優秀なコミュニケーションツールとなります。時間がかかってでも丁寧に書くことをお勧めします。
サンプルとして、今回説明した内容をもとに、実際に設計書を作りました。
それでは、良いドキュメントライフを。
読んでいただきありがとうございます。