📝

開発チームでドキュメントを継続的に保守していくシンプルな方法

2023/10/23に公開

はじめに

ドキュメントの管理方法はプロジェクトを進めるうえで頭を悩ませる話題のひとつであり、プロジェクトの本筋ではないこともあってなあなあで運用して後悔しやすい部分になります。ドキュメントを探しづらくなったり、ドキュメントが全然更新されずに使えるドキュメントがほとんどない状況になったり、ドキュメントの存在自体が暗黙知になったり、とにかく諸々の問題がよく起きます。こうしたことからプロジェクトに与える影響は存外に大きく、きちんと運用を考える必要性は高いと言えます。しかしながら、大袈裟な運用体制を敷いたり複雑なルールを作ったりすると、今度はコストが掛かり過ぎたりドキュメントを書くこと自体が難しくなったりもするので、費用対効果を考えると匙加減が難しい話でもあります。

そこで、本記事では比較的導入しやすく機能もしやすいシンプルな管理方法を提案します。なお、シンプルさを優先した方法なので要点を理解した人は自由にアレンジしても良いでしょう。

先にまとめ

例えば開発チーム単位でのドキュメント管理は、以下の3つの原則によって運用する方法があります。

重要なドキュメントは全てオンボーディングドキュメントに直接または間接的にリンクし、リンクを辿るだけで容易に到達できるようにする
オンボーディングに必要なドキュメントはきちんと更新するということをチームのルールとして設定し、周知する
責任者（通常はリーダー）が責任をもち、特にチームに新規加入者がくる時などに必要に応じてドキュメントの更新またはアーカイブを行う（あるいは適切なメンバーに更新を依頼する）

また、継続的に更新したい重要なドキュメントにタグを付与し、検索によって一覧を作って更新日時を確認しやすくする手法を併用するとリンクが増えた場合にも対応できます。

ドキュメントが更新されない理由

そもそも何故ドキュメントが更新されないのでしょうか。

これはほとんどの場合、以下の3点が問題になっているのではないかと思われます。

ドキュメントが分かりにくい場所にあり、更新が必要なタイミングになったとしても探せなかったり存在に気付かれなかったりして更新が漏れる
誰がどんなときに見るのか、ドキュメントの利用者やユースケースの想像がついていない（更新する意義をさほど感じないので更新しない）
チームとしてドキュメントを重視していない（ドキュメントを更新する作業に工数を使いにくい雰囲気がある）

どのドキュメントがどこにあって、それは重要なのか、更新しても見る人がいるのか、工数をかけてまで更新する意義はあるのか、といったことが不明瞭だと、更新する意義がわからずに手間をかけてまでドキュメントを更新する気にならないという状況に陥りやすくなります。チーム自体がドキュメントを重視していない場合も、ドキュメントの更新がチーム的には求められていない仕事となってしまい、周囲の目を気にして別の作業をやった方が良いとなることが少なくありません。

他にも色々とあるかもしれませんが、以上の3点を解決するだけでもドキュメント運用がかなり改善されるものと思われます。

ちなみに、ドキュメントを継続的に更新していくよくある方法として、例えば重要なドキュメントはタグなどでマークして定期的に確認するようなアプローチも度々見かけますが、いつだれがそのドキュメントを利用するのか？ という部分に対しては上手い回答を用意できていないものも少なくなく、もう一押し欲しいところです。

オンボーディングに集約する

では、具体的にはどのようにドキュメントを管理していくのが良いのでしょうか。

ここでの考え方として、そのドキュメントが更新されないとどういう害があるのか、更新することでどういったメリットがあるのかを認識しやすくすることが何よりも重要です。つまりはユースケースを考えるべきでしょう。

さて、継続的に更新するべきドキュメントのユースケースについて、主だったものとしてはどのようなものがあるでしょうか。これはやはりオンボーディング時に参照するのが最も主要なユースケースになるのではないでしょうか。

よって、基本的にはオンボーディングドキュメントに重要なドキュメントへのリンクを全て記載することをお勧めします。繰り返し参照されるドキュメントであればどこかに導線が欲しいので、その導線を一旦オンボーディングドキュメントに集約して置きましょうということです。重要なドキュメントなら新たに参加したメンバーも読んだほうが良いものも多いだろう、という考えもあります。オンボーディングで必ず読むべき範囲と必ずしも読まなくても良い範囲を明確に区別すれば、リンクが多くても実用上あまり困らないはずです。

少なくともオンボーディングドキュメントが古いと新規加入メンバーの作業に支障が出るという実害があるのは明白であり、更新する動機としてはかなり自然です。内容が古い資料を使ってオンボーディングを行うといちいち補足を入れていかなければならなず、無駄な時間がかかる上にそのあとで直すと二度手間になるだけなので、少なくとも新規加入者が来るタイミングで修正した方が合理的でしょう。

オンボーディングドキュメントに集約することによって、いくつかのメリットを享受することができます。

オンボーディング時の説明が楽になる
新規加入メンバーとしても資料を探すのが楽になる
ドキュメントを更新する意義が明確になる
チームに新規加入がある度に見直す動機があり、資料が集約されていることによってオンボーディングの質も担保しやすくなる
オンボーディングドキュメントを見に行けば大体のドキュメントに辿り着けるので「あのドキュメントどこにあったっけ？」となることが減る
更新すべきドキュメントがどれなのかがわかりやすくなり、更新作業の範囲も明確になる
ドキュメントを作ったらとりあえずリンクしておけばいずれ見られることが概ね保証されるので、ドキュメントの作成・保守のモチベーション向上につながる
ドキュメントをどのフォルダに配置するかで悩む必要がほとんどなくなる
ドキュメントの存在が目に触れやすくなり、不要になったものを捨てて整理する機会が増える

議事録やADR、障害報告など流動的に生まれるドキュメントの置き場所を包括的に示したい場合は、単純に一覧のリンクを書いておくのが良いと思います。ドキュメント管理に利用しているサービスによっては、一覧のリンクを表現するには検索クエリが付いたURLを使うくらいしか方法がないこともありますが、それでもそこまで困らないと思われます。

なお、リンクの量が膨大になる場合、この方法だけだといくつかの問題が生じることはあります。

まず古くなったページがどれなのかをチェックするのがとにかく大変になることが挙げられます。前にタグを付与する方法について軽く触れましたが、単に古くなったものを更新したいだけならこの方法が単純で分かりやすいので併用するのが良いでしょう。こちらの方針での運用は下記の記事も非常に参考になります。正直、下記の記事の運用が出来るなら別に本記事は忘れてもらっても構わないくらいです。

また、単にページが縦に長くなって一覧性・可読性が悪くなることも挙げられますが、ページを入れ子状にして整理するなど工夫の余地はあります。しかしながら、ネストが深くなると全体像がつかめなくなる他、ページ内検索でヒットしなくなるなどしてUXを損なうこともあります。長いページを見ると整理したくなる欲求が湧いてきますが、リンクが一つ深くなるだけで目に触れる機会が減りやすいということも意識しましょう。

ちなみに、オンボーディングドキュメントにリンクするのが明らかに適当ではなさそうなドキュメントとして唯一オフボーディングドキュメントがあります。こういったものは1段上にインデックスドキュメントを作るなどの手段がありますが、愚直にオンボーディングドキュメントにリンクしても良いと思います。オンボーディングプロセスが増えた時にオフボーディングプロセスを併せて確認する需要はありますし（しかも結構忘れやすい）、存外に悪くはありません。なお、インデックスドキュメントを作る運用でもその存在を示すためにオンボーディングドキュメント内にリンクを記載する必要があり、結局構造的には大同小異だったりもします。

運用にあたって

「オンボーディングドキュメントに集約する」という方針は非常にシンプルであり運用しやすいことも魅力のひとつです。しかし、運用にあたってはきちんとチームの理解を得てから実施しましょう。チームのカルチャーを作るような話でもあるので、メンバーの理解を得ずに行えるものではありません。メンバーによっては別の方法が良いと考えているかもしれませんし、チームによってはこの方法が適切ではないこともありえます。何より、こういったルールを勝手に導入すると押し付けられたように感じるなどして反感を買うことがあるので注意しましょう。なお、ルール化の際は、どうしてもすぐにドキュメントを更新できない場合は簡単な報告をしつつタスクにするように、くらいのトーンにしておくと無難です。

ドキュメント管理における責任者を立てておくことも重要です。ドキュメントのユーザーは書いた人・書く人とは別の人であることが多いため、ドキュメントの保守についてオーナーシップを持ちにくく、責任者がいないと形骸化しやすい傾向があります。また、責任者というロールを持っていれば音頭を取りやすいという側面もあります。

古くなったドキュメントへの対応方法も大事です。最も避けたいのは古いドキュメントが多くてドキュメントそのものに対する信用が低下した状態になることです。しかし、現実問題として更新が必要なドキュメントを全て保守していくことが現実的ではないことは多々あります。そういった場合では、まず特に優先度の高いものだけを更新し、残りは一度アーカイブしてしまい、優先度の高い順に更新してアーカイブを解除していくことをお勧めします。アーカイブだと過剰である場合は陳腐化した部分だけ注釈をつけても良いでしょう。費用対効果が低いものを切り捨てていくのも大事な考え方であり、無理せず保守できる範囲に上手くまとめていきたいことろですが、必要なものまで切り捨ててしまうと本末転倒なのでその判断は難しいです。なお、いくら古くなったからと言ってドキュメントを完全に削除するのは問題の火種になるので余程の理由がない限りはやめておきましょう。

注意点

この運用方法を適用する際、タイトルの変更でURLが変わるタイプのサービスだとリンク切れが発生しやすくなります。そのため、タイトルを変更するときはリンクも書き換えるというルールを追加する必要があります。不便ではありますが、タイトルを変更する機会はそれほど多くないこともあって致命的というほどではないでしょう。

最後に

これはあくまでシンプルな運用でドキュメントを保守していく方法のひとつでしかありません。
例えばチーム内で細かくロールが分かれていてオンボーディングの内容も違うみたいなケースだと本記事の方法そのままは適用しにくかったりするので多少のアレンジは必要になりますし、そもそも適合しないケースもあると思います。ドキュメント管理は現場によって前提条件が大きく変わってくるので、こういったドキュメント管理の方法論は「あくまで一例」の域を出ることはないというのは何とも歯がゆいところではあります。基本的にはドキュメントが最新でないことで「いつ」「誰が」「どの程度の頻度で」「どのくらい」困っているかを考えると対策を講じやすいですが、検討した結果として費用対効果が微妙であるという結論に落ち着きがちなのもドキュメント更新の難しさと言えるところです。そういう意味でも本記事くらいのシンプルな運用が導入しやすいのではないかと思っています。そして、運用していくうちに改善点が見つかったら柔軟に対応していけば良いでしょう。

蛇足: 発展的な運用を考える

「オンボーディングドキュメントに集約する」というルールは分かりやすいですがひとつのユースケースに強く依存しているため、発展的な運用を考えたくなることもあるかと思います。なのでその参考にできそうな話を少し蛇足として置いておきます。

ドキュメントの管理方法として「カテゴリごとに分けた目次やフォルダ階層を作って機械的に分類して管理する」という形式（階層整理型 wiki スタイル）を取りがちですが、この方法は破綻しやすいです。例えばいくつかのドキュメントは1つのカテゴリのみに属するわけではないはずで、複数のカテゴリにまたがるドキュメントをどこに配置するか？という問題によって容易に例外が発生します。そもそもどう分類するかの基準が人それぞれ異なるので一瞬で無法地帯化……とまでは言わずとも階層の粒度がバラバラ、未分類も発生して探しにくい状態になりやすいです。

階層整理型 wiki が破綻しやすい話は Scrapbox のコンセプトでも言及されています。本記事で解説した運用方法も Scrapbox のようなネットワーク型ノートの思想の影響を受けています（直接的にはどちらかというと Obsidian の MOC の影響で発想したものではある）。階層構造に拘らずリンクを主体に構成し、必要なら相互にリンクするくらいの方が使いやすくなります。ネットワーク型のノートの運用方法から学べることは多いので発展的な運用方法を考えたい方は調べてみると良いアイデアを得られるかもしれません。