チームがもっているドキュメント置き場があって、これを整理しましょう的な話がでてきた。ので、どういう感じで整理したらいいかを考えてみる記事。明確なこうすべき！！！という案はないけれど、こういうことをしたらいいんじゃないかな〜というのはある。
そもそもの課題感としては、ドキュメントをどこに書いたらいいかわからない、重複したものがあるかもしれない、そもそもない、情報が古い（更新しつづけられない）、散らかっている、などなど。
ドキュメントの配置に階層構造をつける
現代的なドキュメント管理ツール（？）、NotionとかConfluenceとかKibelaとかGoogleDriveなら階層構造をつけられるので、ドキュメントの大まかなカテゴリ分けができる。
どんな配置がいいのかはそのチームの性質にもよるので一般化は難しい気がする。
たとえば何かしらのバックエンドなシステムを開発しているチームだったら、こんな感じだろうか？
- チーム外向けのページ
- チーム
- 扱っているシステム
- システムの利用方法
- 開発ガイド
- …
- チーム内向けのページ
- オンボーディングガイド
- インストールするべきツール
- リポジトリのセットアップ
- 最初のリリースをするまでの道のり
- チーム運営
- 開発フロー
- ロールの明確化
- デイリーミーティング
- 振り返り
- オペレーションマニュアル
- オンコールの取り方
- メンテモードのやり方
- DB操作のやり方
- DesignDoc/ADR
- …
- プロジェクト
- xxxプロジェクト
- 概要
- checkin
- yyyプロジェクト
- 概要
- checkin
- xxxプロジェクト
- ナレッジ
- AAA技術の調査記録
- …
- オンボーディングガイド
チーム内外にわけたのは、“チームドキュメント” のスコープが曖昧だから。違うチームの人が、どれどれあなたのチームのシステムを使いたいんだけどどうするのかな？と覗いてくるようなシチュエーションを考えている。
逆にチームが頻繁に同期されて、やることもわりとシンプルなのであれば、フラットな構造で、決定事項とか議事録とかを雑に書いていけば十分だと思う。
- AAA技術の調査
- xxxプロジェクトのzzzについて
- 2025-09-01 定例
- …
あるいは複数のシステムやプロダクトを扱っていて複雑なら、もっと分離したくなるかもしれない。
- AAAプロダクト
- チーム外向け
- チーム内向け
- BBBプロダクト
- チーム外向け
- チーム内向け
- CCCプロダクト
- チーム外向け
- チーム内向け
あるいはこうか。
- チーム外向け
- AAAプロダクト
- BBBプロダクト
- CCCプロダクト
- チーム内向け
- AAAプロダクト
- BBBプロダクト
- CCCプロダクト
でも結局は同じ話で、いったん自分たちがわかるならフラットな構造でも何でもいい。あるタイミングで、これはやっぱり分けたほうがいいね、となるときが来る。
ここまで大きくなるなら、もしかしたらそれはチームを分けたほうがいいタイミングなのかもしれないけれど。
ともかく、これでドキュメントの配置場所に関わる課題を解決できるし、重複したものがあるかもある程度判別できる。
ドキュメントは進化させていく
前にもそんな話は書いた: ドキュメントを育てていく
初手から最強にはならない。知識や経験でショートカットは可能だけど。
それから随時更新というのは難しい。ので、気付いたら適宜更新していきたい。 （今ならAIに丸任せで、ページツリーとリポジトリを渡して「全ページ更新して」もできそうな気もするが…）
これはドキュメント配置に関しても同じ。たぶん最初はフラットで書き始めて。だんだん構造が作られていって。最適化されて。そしてまた大きくなって階層を整理して。
ドキュメントを整備することが価値に直結しないのなら、優先度は高くしなくてもいいのかな〜とは思う。書かれている情報が古くて困るか？困るなら更新したほうがよい。情報が書かれていなくて困るか？困るなら記載したほうがよい。困らないならそのままでよい。
何にしても定期的に自分たちの立ち位置を見直すことが大事。
これで情報が古い（更新しつづけられない）は解決。
プラットフォームが提供する機能を適切に使う
ドキュメント自体の話になっちゃうけれど、各プラットフォームは様々な機能を提供している。
- 見出し
- 太字
- 斜線
- 取り消し線
- リンク
- コードブロック
- 表
- 画像
- 複雑なレイアウト
- グラフ
- その他埋め込み
それらを適切に使うことで、ドキュメントのみやすさが格段に上がるので、積極的に使っていきたい。難しかったら最低限見出しだけでもつけるとよい。
まあ、結論としては、どう整理するかはチームがやりたいことによるので、チームで対話して決めていけるといいな。見通しが立たなかったら、いったん雑に決めてしまって、それを土台に整理していったらよいと思う。やらないとわからない系だと思う。