モチベーション

仕事でドキュメントツールをコンフルに寄せる方針になりました。
今の現場ではドキュメントの運用ルールがあやふやで、そもそもその運用ルールを決めてあげないと既存のドキュメントのただの移管作業となっていまいドキュメント自体いるのか？という話になりそうでした（要は、ドキュメントを重視しなくなってしまう）

個人的には、ドキュメントがあるとチーム内の認識の齟齬の防止やコミュニケーションコストの軽減などチーム開発においてメリットが大きいためしっかりと運用指定行きたいと思います。

しかし、自分であまり運用ルールを考えたことがないのに加え、あまりしっかり言語化したこともありませんでした。
そのためで、まずはドキュメントの種類や考えられうる課題点を調査して現場に生かしていけるような叩き台のルールを決めに行きたいと思います。

参考記事

・HTTPキャッシュに学ぶ、無理のないドキュメント更新運用：ドキュメントの鮮度をためつための仕組み。かなりファットな仕組みである。今のチームメンバーは十人もいないためもう少しコンパクトにできないか考えたい
・クラウドネイティヴ時代の運用を考える 〜 ドキュメント駆動運用へ：ドキュメント運用を目的から見た理想像が書かれている。ドキュメント運用のベースとなりうる考えになりそう。
・GoogleのDesign Docsから学ぶソフトウェア設計：これはGithub discussionとコンフルの棲み分けになりそう

現状

・チーム内のメンバーは業務委託が半数以上で10人以下→工数はあまりかけたくない
・ドキュメントの運用ルールがない→文化の浸透のため、ドキュメント更新の理由も共有できないと陳腐化する
・openapiからコンフルにAPI仕様書を寄せる
・今後は、コンフルとgithub discussionsが利用される想定。

理想

・工数をかけず、なおかつチーム内でドキュメントの必要性を感じながら必要なドキュメントの更新を怠らない
・ドキュメントの記入・作成ルールを設けて、人によって記入粒度や作成箇所が異なるのを防ぐ

ギャップ

・ドキュメントとひとくくりに捉えており、各ドキュメントによって必要な対応や鮮度が異なるはずなのでその種別や役割によって、記載内容や運用方法を考えたい。
・ドキュメントのディレクトリ構成を考慮
・欲しいドキュメントがどこにあるのか拾いにくい