技術的な合意形成を円滑に進めるためのドキュメントの書き方
Makuake Advent Calendar 2023の23日目の記事です。
今回は技術的な内容ではないですが、技術系、特に調査検討系のドキュメントを書くときに自分が気をつけていることを書いていきます。意思決定それ自体のhowtoについてはフレームワークとか色々あると思うので、選定の仕方ではなく合意形成を進めるためのドキュメントの書き方に焦点を当てられればと思っています。
対象になるドキュメント
調査検討系のドキュメントってなんだろうというところから。
調査検討とは
色々な解釈がありそうですが、ここでは「課題を解決するための方法を検討して、それをステークホルダーと合意すること」とします。成果は検討結果ではなく合意形成です。
課題としてのイメージは下記の通りです。
- 何らかの新機能
- バグの修正
- パフォーマンスチューニング
- 運用改善
- など
よって、事実を記録するためのドキュメントや、決定事項を単に共有するためのドキュメントはスコープ外です。
目的
- ステークホルダーからの合意を得るため
- 自分も含む将来の運用者が経緯を理解できるようにするため
- これは副次的な目的になりそう
どんなドキュメントであっても「読み手を意識して書きましょう！」と言われますが、上記の目的に沿った場合にどう書けば読み手にとって理解しやすい、合意形成しやすいドキュメントになりそうかというのをご紹介できればと思います。
書き方
それでは本題に入っていこうと思います。
背景や目的を考える
そもそもなんでこの調査や検討が必要になったんだっけ。というのをまとめます。
バグやパフォーマンスチューニングなど解決すべき課題が明らかな場合は書きやすいかもしれないですが、設計上必要な調査の場合、その調査結果が設計にどう影響してくるのかというのをきちんと説明してあげるとともに自分が理解しておく必要があります。
もしかしたら、改めて考えてみると既に結論が出ていたり、大して重要じゃない（≒別の何かの方が重要だった）とか、時間を割いて考える必要が無いことだったりするかもしれません。
他にも、前提知識が必要だったり別の意思決定が関与していたりするなどする場合も明記しておきます。
必要に応じてスコープも記載する
調査範囲もきちんと明記しておきます。
逆に、今回の調査内容について何か制限があるならそれも書いておくべきです。「検討しないこと」みたいな項を設けても良いと思います。
<Check> 読み手がコンテキストや調査の意義を理解できるか？
要件を明らかにする
解決したい課題の要件を明記します。実現したい機能だったり、解決したい性能劣化だったり・・・。何が満たされればその課題が解決されたと言えるだろうか というのを言語化します。また、数値化できるものであればできるだけ数値化しておきます（例えば、来月までにスループットを5倍にしたい とか）。
<Check> 要件の認識がずれていないと自信を持って言えるか？
選択肢を洗い出す
要件を満たすために思いつく方法を洗い出します。自分だけの知識や視点だけだと足りてなかったりするので、ブレストしたりするのも良いかと思います。
基本的にはここで洗い出した選択肢から選んでいくことになるので、可能性はできるだけ潰さずに列挙していくようにしています。
とはいえ、要件から外れてたり、実現性低かったり、あっても絶対選ばれないだろみたいな選択肢についてはノイズになるし、検討する時間が無駄になるので一応どこかにメモはしておきつつも、早々に除外しておきます。
<Check> 必要十分な選択肢を洗い出せていることを理解してもらえるか？
選定基準を決める
要件と選択肢から、選定基準を明らかにします。コストやスケジュールだったり、意思決定マトリックスの評価項目や非機能要件（可用性、スケーラビリティ、保守性etc）から持ってきたりします。ツールやSaaSの選定であれば、それ特有の観点も出てくるかと思います（Email配信基盤であればバウンス管理方法や配信速度など）。
ここまでで洗い出した選択肢については基本的にどれを選んでも要件は満たせることを前提としているので、選びきるために選定基準を優先順位を付けておきます。
<Check> 優先順位や選定基準が選ばれた理由を説明できるか？
選択肢を評価する
あとはドライに比較検討を行うだけですが、予想と全然違う結論になったり、あまりに予想通りの結論になったりした場合は、少し立ち止まってして考えるようにしています（観点漏れてないか？選定基準はこれでいいか？）。
最後に、選ばれた選択肢を実装し、課題が解決された後の事にも少し思いを馳せてみて、イメージが付けば多分大丈夫。
結論を端的にまとめる
最後に、決定内容を経緯をサマったら完成です。後から要点を見返すのにも良いし、隅々まで読み込む時間が無い人もいるかもしれないので。
伝える！
合意形成までがゴールなので、ステークホルダーに対して誠意を持って説明し、フィードバックをもらいます。厳しい意見をもらっても泣かない。
まとめ
書いてみるととても平凡な内容になってしまいましたが、アドカレに乗じて（？）スムーズに合意形成を進めていくために最近重要だなーと改めて感じたことを明文化させていただきました。
誰かの参考になれば幸いです。
Discussion