この記事は 🌊 UMITRON 🐟 Advent Calendar 2022 6日目 の記事です。
ウミトロンでは、会社のドキュメント共有ツールとして Notion を使用しています。
以前は Confluence を使用していました。
私自身も Notion を使うのは初めてだったのですが、せっかく使い始めるのだから、上手に活用したいという思いがありました。
この記事の中では、現在のチームで策定し、現在も試してみている Notion の運用方針について、概要を記載しています。
なお、ウミトロンは現在、プロジェクト制を取っており、全社としての方針 (Values とか Guideline とか) はありますが、細かい運用は各プロジェクトチームに任されています (分割統治を行うことで、各チームが機動的に動ける体制が取られています)。 ここに書く内容は、主に私が属しているチームでの話になります。
Notion 移行前の振り返り
まず Confluence から Notion に移行するにあたって、これまでのドキュメントの残し方について、良かった点・悪かった点をリストアップすることにしました。
良かった点:
- 全員積極的にドキュメントを残している
- ウミトロンの Values にも含まれていますが、きちんと記録を残し、共有する文化は確実に根付いています
- 全社共通のドキュメント以外は、プロジェクトごとのスペースに残せるようになっている
- 自分の管轄の範囲外のスペースは一気に記載のハードルが上がるため、分割統治できるレベルまで落とした、 安心して記載できるスペース があるのは重要です
悪かった点:
- 定期的に開催される打ち合わせのメモがコピペでどんどん増殖する
- 週次ミーティングなどでは、 前回からの差分 を確認したいため、まずコピペで前回の状態を復元するのがよくやられていました
- しかし、これだと、同じキーワードが少しずつ形を変えてどんどん増えるため、 検索結果を汚染 してしまっていました
- 本来広く共有すべき情報が、個人スペース (より狭い共有範囲) に残されがち (ステルス化)
- タスクの記録等は、共有のスペースだと、ディレクトリ構成などの整理の仕方で、他の人に気を遣ってしまい、結果 個人のスペース に書いてしまいがちでした
- しかし、個人スペースにあると、他の人が内容を更新しようと思っても更新しづらくなります
- Confluence, Slack, GitHub, Wrike など、複数の媒体にドキュメントが散逸している
- ドキュメントを残す媒体が複数あり、それらの使い分けについて、明確なガイドラインがないことが根底にありそうでした
- あまりに散逸すると、 必要な情報がどこに書いてあるのか 探しづらいです
- 同じことを書いたドキュメントが複数存在することがある
- まず既存のドキュメントがないか調べてから書くべきなのですが、目的のドキュメントを探しづらいというのが理由の一つにありそうでした
- 結果、 車輪の再発明 となり、 二元管理 にもなります
まず、良かった点は引き続き継続するべく、新しい運用においても、あまり細かいルールで縛りすぎないように、心がけました。また Notion でも、引き続きプロジェクト/チーム別の階層構造が導入され、チームごとに最適な形態を取れる体制が取られました。
一方で、得られた反省点については、なるべく シンプルな運用方針 と Notion 特有の機能 を利用して、改善を図ることにしました。
ドキュメントのタイプ分け
そこで行ったのが、ドキュメントのタイプ分けです。以下のようにドキュメントのタイプを大別しました。
| タイプ | 性質 | 長期的な参照頻度 | 最近の情報に保つべき | 属人性 |
|---|---|---|---|---|
| ドキュメント | 頻繁に参照される、構造化しにくい情報 | 高め | Yes | 低い |
| データベース | 頻繁に参照される、構造化できる情報 | 高め | Yes | 低い |
| 作業ログ (兼 タスクチケット) | 日々のタスクで発生する情報の記録、整理 | 低め | No | 高い |
| 議事録 | 定期的な進捗確認や議論 | 低め | No | 低い |
(ややこしいですが、最初のタイプのものを、狭義の "ドキュメント" と呼んでいます。他によい呼び方が思いつかなかったので...)
"ドキュメント" / "データベース"
まず、ドキュメントの参照頻度については、以下のようなパレードの法則に近いことが言えると考えました。
- "ドキュメント参照回数が高いものは、ごく一部のドキュメントで占められる"
- "ドキュメントの多くは、作られた直後には多く参照されるが、時間の経過とともに参照されにくくなる"
ドキュメントについては、日々の開発等の中で、しばしば情報が古くなってしまいがちですが、 最新の情報に保つべき対象を、長期的に見ても参照頻度の高い情報に絞る ようにしました。また、これらについては、属人性が低いことを強調し、誰もが更新しやすくなるようにしました。
ドキュメントの数を絞り、階層化して管理する ことで、何がどこにあるのかをチームメンバーや Newcomer が把握しやすくなり、ドキュメントの更新を怠らなくなることを期待しています。
さらに、これら、長期的な参照頻度が高いものの中でも、構造化できるデータについては、 Notion のデータベースで管理するようにすることで、情報の相互の紐付け等 Notion ならではの機能をフルに発揮できるようにしました。
"ドキュメント" の例としては、以下のようなものがあります。
- Newcomer 向けの導入
- リリース手順
- 各種ガイドライン
"データベース" の例としては、以下のようなものがあります。
- リリースノート
- コードレビューチェックリスト (レビュー時によく出てくる指摘事項を Notion のデータベースに登録。ノウハウも溜まってくるし、抜け漏れも減る)
- 設定値リスト
注意点としては、これらの参照頻度が高いドキュメントについては、誤って記載内容を更新したり、消してしまったりする危険性が高くなります。 Notion にはロック機能があるので、こうしたドキュメントに対しては、積極的にこの機能を使うようにしています。
作業ログ (兼 タスクチケット)
一方、長期的な参照頻度が少ないと思われる日々の作業内容に関する記録については、以下の方針で管理することにしました。
- プロジェクトごとに Notion のデータベースを作り、そこで一括管理する (タグ付け等はするが、階層構造にはしない)
- データベースの各アイテムは、タスクチケットも兼ねているので、アサイン (担当者)、ステータスや開始日、終了日等の属性も持たせておく
- 何かタスクをアサインしたり、作業を行った場合には、必ずこのチケットを作り、作業内容を記録するようにする
担当者が決まっているので、この作業ログについては、属人性は高くなりますが、以前のように個人スペースの中に記載しているわけではないので、検索等がやりやすくなります。また、階層化していないため、こうした記録を保存する場所に悩む必要がなくなります。
これらの作業ログは、長期的な参照頻度は高いとは言えませんが、それでもたまに確認したいケースが出てきます。 Notion は特定の階層配下に絞った検索が可能 なため、このプロジェクトの過去の実装の経緯を確認したいとなったときに、このデータベースを対象に検索を行えば、その経緯が書いたメモにヒットする可能性が高くなります。
さらに Timeline view で見ることによって、日々の進捗管理の用途にも利用できますし、後述の (特に定期開催のミーティングの) 議事録の中で、この作業ログの Linked database を作ることによって、コピペを繰り返すことなく、前回からの差分の確認を行うことができるようになりました。
作業ログの中身の形式については、特に規定は設けていません。
私の場合は、タスクの粒度がそこそこ大きめの場合、チケット内に inline database を作り、そこでサブタスクを定義したり、見積もりの洗い出しに用いたりもしています。
議事録
上述した議事録の問題点として、コピペが増殖する点がありました。
これらに対応するため、定期開催のミーティングの議事録については、 Notion の Linked database を積極的に活用するようにしました。
Linked database は単なるショートカットであり、実体は別のところにあるため、それを複製したとしてもコピペにはならず、情報の一元管理になりますし、検索結果も汚しません。
ただ、その反面、運用をうまくしないと、過去の議事録の内容が、時間の経過とともに更新されてしまいます。私達のチームでは、上記の作業ログのチケットに、議事録ページのリレーション属性を設けることによって、両者の紐付けを行えるようにして、これを解決しています。
議事録のそれ以外にスペースには、議論したことなど、 本当に重要な情報だけを記載 することで、本来の目的を達成できるようにしています。この議事録自体も、データベースとして管理しているため、その配下だけを対象とした検索をかけることで、必要な情報だけを探しやすくしています。
具体例
Q. 実装について他の人が理解しやすいようにまとめたものはドキュメントにすべき?
それを調査した時点でのまとめであり、時間の経過とともに内容が古くなってしまいます。
そのため、あるまで "xxx実装についての現状調査" みたいな作業ログ (タスクチケット) を作って、その中に記載するのがよいと思います。
新規実装の場合では、最初からその実装についての作業ログ (タスクチケット) の中に書くといいでしょう。
それによって、あとから参照する場合でも、その時点における実装なんだなと理解することができます。
非常に参照頻度が高いまとめについては、ドキュメントから作業ログへのリンクを貼るか、ドキュメントとして昇格させても良いと思います。
他ツールとの使い分け
反省点の中にあった、複数の媒体にドキュメントが散逸する問題についてですが、特に Slack 等のコミュニケーション手段、および、開発の人間なら、実際のコードや GitHub 等の Issue/Pull Request などへの記載を併用することは、避けては通れないでしょう。
前者については、口頭で話したことも含みますが、議論の要点や結論については、 Notion の作業ログなり、議事録なりにまとめておくことを心がけています。 GitHub の Pull Request 中で議論したことも同様です。
後者についても、これは賛否両論あると思いますが、なるべく今は Notion に寄せるような方針で試してみています。情報の一元管理の観点もありますし、 Notion なら図や動画などの表現力が豊かで、 biz の人も編集に加われるというメリットもあります。 Pull Request のテンプレートには、 Notion ページへのリンクを貼れるようにしています。
ただ、コード中のインラインコメントも重要であるとは考えているため、そちらもなるべく記載するようにしていますが、複雑なものについては必要に応じて Notion のリンクを貼ったりしています。
最後に
少し誇張気味に、全てうまく行っているような書き方をしてしまいましたが、概ねいい感じには運用できている手応えを感じています。
ただ、ドキュメントの管理方法には正解というものは無いと思います。
例えば、 OSS プロジェクトや顧客向けなど、全ての公開ドキュメントの更新が必要なシーンではまた違った運用が求められると思います。
これからもプロジェクトの人数、規模やステージに応じた、最適な方針を模索していきたいと思います。
ウミトロンでは、私たちと一緒に「持続可能な水産養殖を地球に実装する」仲間を積極的に募集しています。
このミッションのもと、テクノロジーを用いて水産養殖の課題に挑む航海に共に出てみませんか?