アンドパッドの土方です。
本ブログではEMインタビューで取り上げておりますが、記事投稿は初めてです。
エンジニアマネージャーとしてのイベント登壇や、プロジェクト推進における案件の取りまとめ業務が増えてきており、それに伴ってドキュメントを作成する機会も増えてきました。
自分の考えを整理するとともに、アンドパッドのエンジニアにはこんなこと考えている人もいるよ、的な意味で紹介したいと思います。
何かの参考になれば幸いです。
結論！
次項からは文字ばっかりで語っているだけになりますので先に結論を書きます。
- 断面を作るための切り方を意識する
- 網羅性、単一性を守る
- 二軸で表現する
この三項を守ることで、理解されやすく誤解を招かないドキュメントの完成に近づけると考えています。
ではここからだらだら語ります。
ドキュメントの目的は？
そもそもドキュメントはなんのために作るものでしょうか。
私は、「認識を合わせること」が目的であると考えます。
- 決定した事項や状況について関係者間で共有し認識齟齬を防ぐ
- 読み返すことで過去の自分がどう考えていたのかを思い出し、今の自分の認識とのズレを意識する
- 未来の自分に向けて、現時点での認識を知らせる
- 今、自分が実はどう考えているのかを整理し認識する
この目的を達成するためには、ドキュメントに何が書いてあるのか？読む相手が理解でき、誤解しないことが必要になります。
理解できなければ合わせるべき事項や状況を認識できず、また誤解があると認識を合わせることが出来ず、せっかく作ったドキュメントが無駄になってしまうだけではなくかえって認識齟齬を生んでしまうことになります。
口頭での補足説明を加えることで理解してもらう、誤解を解く事もできますが、せっかくドキュメントを作る時間を割くわけですからドキュメントだけで完結することを目指したいと思っています。
断面の積み重ね
ドキュメントに起こそうとしているもの - プロジェクトや開発システム - の全体像は、具体的に形があるものではなく、それぞれの頭の中に不定形なイメージとして捉えられていると思います。
不定形なイメージの認識を合わせるために私が考えていること、それは輪切りにすることです。
輪切りにするときに切った面が断面ができるわけですが、この断面を積み重ねていくと立体となり、全体像が現れます。
不定形なイメージを共有することは難しいと思いますが、自分なりに断面を複数作り、それを積み重ねていけば自分なりの立体を理解してもらうことができるはずだと考えます。
このとき、乱切りで切ってしまうと重ね方で認識が合わなくなってしまう可能性がありますから、切り方を統一し断面はすべて同じ角度になっていることが必要です。
そうすれば、断面を積み重ねることができます。
ここでいう切り方が、ドキュメントの種類だと思っています。
- 画面デサインの角度で切ると画面一覧
- エンティティ, テーブル定義で切るとER図
- 実装機能で切ると機能一覧
Excelで作った場合、シートの数が断面であり、すべてのシートを積み上げることでシステム全体像が見えてくるというわけです。
また一つの角度からだけではなく、様々な角度で切った断面から表現したドキュメントを組み合わせることで、システムの全体像がより理解しやすくなります。
網羅性と単一性
断面からドキュメントを作り全体像を表すわけですが、組み合わせて全体像をあらわすために特に下記の2点を気をつけています。
- 網羅されていること：漏れがない
- 重複しないこと：単一性
網羅されていること：漏れがない
こちらはまあ当然といったところでしょうか。
情報に漏れがあると、積み重ねた結果に欠落があり全体像をあらわすことができませんし、他の切り口で作成したドキュメントとの矛盾、齟齬が生じてしまいます。
また記載情報の漏れだけではなく、図を使うときには凡例を必ず付けることを心がけています。
図を書く上で記号が何を表しているのかは非常に重要で、認識齟齬を生まないためには必須です。
重複しないこと：単一性
口頭でのコミュニケーションでも非常に重要だと考えているのですが、ドキュメントにおいても重複しないことは非常に重要です。
特に重複することを防がなければならないこと、それは名前です。
ドキュメント作成やコミュニケーションにおいてはいろいろなものに名前をつけます。
機能名、画面名、ドキュメント名、事象名（特に不具合発生時や案件のキックオフ段階において）などなど。。。
名前の重複には2つの意味があります。
- 同じものに複数の名前をつけてしまう
- 違うものを同じ名前で呼んでしまう
いずれの場合においても、認識の齟齬を招きドキュメントの作成する意味がなくなってしまうと思います。
プロジェクト開始にあたっては、すべての事象に予め名前をつけ重複することを防ぐ。間違えたら罰ゲーム！
くらいの防止策があってもいいように思います。
図を使う場合の、記号についても同様です。
名前と同様に、一つの記号は一つの意味とし、例えば○を人物と組織の両方に使うことのないよう注意しています。
二軸で表現する
ドキュメントは、二次元空間である平面上に記述していくことが殆どだと思います。
平面上に表現できるのはX,Yの二軸でありZ軸を正確に表現することは出来ません。
それっぽく表現することは出来ますが、色や点線などを利用して平面を立体的に認識させているのであり、誤解を生みやすい表現となってしまいます。
※このあたりはそんな誤解を利用した表現だと思います
ja.wikipedia.org
ja.wikipedia.org
平面で表現する以上、平面に存在できる二軸を超えた軸で表現することは避けるようにしています。
おわりに
ここまで書いてきましたが、最も重要なことは目的「認識を合わせること」を達成することです。
目的が達成できれば方法論は何でもいいわけで、条項に囚われすぎて目的を見失わないよう私自身も注意しています。
とはいえ、自分が日々どう考えているのか、どう行動しているのか、分析する時間を取り解像度を高めていくことで考え方の整理、改善ができると思います。
特にドキュメントを作成する前に少し考える時間をとることで、わかりやすい成果物が作成できるのでおすすめです。
アンドパッドでは6Valueを発揮できるよう、日々研鑽を積んでいます。
技術面はもちろん、こういった考え方や取り組み方について解像度を高めたい、周囲と共に成長していきたい方、カジュアルな情報交換からお話にきていただけることをお待ちしております。
