社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ
社内ドキュメントがなぜ更新できないか、更新するためにはどうしたらいいかというお話。主題はドキュメントが更新されるにはどうしたらいいかというお話なんですが、そもそもの前提としてドキュメントにも技術的負債という概念が適用しうるというのが、自分にとって決定的に抜け落ちていた視点なので衝撃を受けました。ということでちょっと書き出してみます。
ドキュメントが更新されなくて辛いというのは日々業務のなかで感じます。せめて自分だけでもドキュメント更新しようと思うのですが、実際に出来るとも限らず、やっぱり更新できずに放置してしまってるドキュメントも数多くあります。ではなぜそうなってしまうのか。それはドキュメントも成果物であって、その製造にはコストがかかり、そして時間とともに陳腐化していくという性質があるからですね。
ソフトウェアにおいては技術的負債という概念が随分と浸透してきたと思います。その解消もいろいろ提案されていますが、現実的にはどの現場でもうまく回ってない印象はあります。まあ、私の経験してる範囲での話ですけどね。
なんで技術的負債の解消がうまくいかないかというと、最大の要因は解消の工数が見込まれてないからだと思うんですよ。どこの現場に行ってもマネージャーは「空いた時間でリファクタリングを進めよう」とは言いますが、リファクタリングのタスクを積んで工数を割り当てるというようなことはしません。まあ、工数見積もるのも難しいって話もあるんですけどね。結果、目の前の機能開発タスクをこなすことが優先になってリファクタリングは進まないと。
ドキュメントについてはもっと悲惨です。そもそもドキュメントを書く工数が確保されてない。「空いた時間でドキュメントも書いといてください」ってことで、そもそもドキュメント作成がタスク化されてません。そんな状態ですから、ドキュメント更新の工数が確保されることがあるわけないんですよね。こうして気が向いた人がたまたま書き散らしたドキュメントがあればまだいい方。その書き散らしたドキュメントも更新されず、何年か経った頃には現状との乖離が激しくなって役に立たなくなってしまう。
ああ、ここで書いたのはあくまでも私の経験してる現場の話です。どっちかというとアジャイル的な開発スタイル(というか、なんちゃんってアジャイル)の現場の話です。ウォーターフォールだと少なくとも最初にドキュメントを作るのは必須ですから、その工数は確保されてると思うんですけどね。そしたら更改プロジェクトの時にドキュメント更新の工数も計上すればいいのにと思うけど、そちらも計上しそうだな。ということはもしかしてウォーターフォールではドキュメントは更新されやすいのか。そのドキュメントが読みやすいか、実際に読まれかどうかは別にして。だとするとドキュメントが更新されないのはアジャイル特有の現象なのかもしれませんね。
(2023/10/18追記)
そもそもの話として、ドキュメントをソフトウェアそのものと同列の成果物として定義しないとダメなんじゃないだろうかという気がした。ウォーターフォールでは当然にそういう定義だろうけれど、アジャイル(っぽい何か)な現場ではドキュメントって気が向いた人が書く、あれば役に立つかもしれないメモ書き程度の認識でとどまってるんじゃないかなと。あくまでも私が経験した現場での感覚ですが。
そうではなくて、そもそもドキュメントにも設計が最初に必要ですよね。どういうドキュメントを作成するか。そこに書く内容はどんなことか。どういう構成で、どういうレイアウトで書くかみたいなことは大筋で決めておいたほうがいい。そして設計が出来ればドキュメント作成の工数も見積もれるし、工数が見積もれればタスク化してスケジュールにも組み込める。
書き出してみたらものすごく当たり前のことのような気がするけど、その当たり前が出来てる現場って実際のところどれだけあるんだろう。そりゃ更新されないドキュメントが放置もされますわね。
(2023/10/22追記)
更新されるドキュメントってなんだろうと考えて思いついたのが、各種社内規定ってやつ。社内規定が更新されるたびに総務の方から掲示板に「〇〇規定が更新されました。〇月〇日から適用になります。」って投稿されますよね。いつも、ああそうなんだぁくらいにしか思ってなくて、更新内容とか気にしたこともなかったですけれども。
ただ、あの社内規定の更新が無意味かっていうとそんなことは全然なくて。社内で仕事をするにあたって、必要になる場面は絶対にあるし、参照するときに常に最新の状態に更新されてないと困るやつですね。そしてこれらの社内規定は更新の作業工数は当然に総務の方のタスクとして割り当てられてますし、また更新されたドキュメントは公開適用されるまえに上司とか専門の士業の方とかにレビューもされてます。なんなら取締役会で承認決議もされてる。それくらい重要で正式なドキュメント。だから更新も必ずされるし、内容が正確であることもある程度期待される。過去の日付で適用される事案もあるから、履歴管理もしっかりされている。本来更新されているドキュメントってこれくらいしっかりと管理運用されてるべきものってことですよね。
一方、更新されてなくて困ってるドキュメントってシステムの仕様書とか手順書とかそんなものですよね。私を含めて主にITエンジニアの間での話題なので。で、なんでこれらのドキュメントが更新されないかっていうと、それは突き詰めて言うと困ってないからかなと思います。
要するにですね、ずっとその会社で働いてるメンバーにとっては、ドキュメントに書くべき内容ってだいたい頭の中に入ってるんですよ。だから普段の業務において、ドキュメントを書く必要性がそもそもない。でも一方困ってる人もいて、それは誰かっていうと新規に参入した人。新入社員とか中途入社の人とかですね。そういう人は当然ながら社内で閉じて何年も蓄積された情報を事前に知る方法はないので、入社してからキャッチアップするしかない。そこで整理更新されたドキュメントがあればキャッチアップも容易なんだけど、ドキュメントがなかったり古かったり欠けてたりする。不足する情報は先輩社員に聞くしかないんだけど、先輩社員も自分の業務で忙しいから、そんな自分にとっては当たり前のことをいちいち質問してくるなよって怒ったりする。そうすると新人は出来ない奴扱いされて居づらくなって辞めてしまう。実際には出来ない奴ではなくて、出来ないようにされてしまった奴なんだけどね。まあ、あちこちの現場でとてもよく見る光景かなって気もします。
この観点で考えると、ドキュメントを作成したり更新したりする目的は、新人を定着させるため。もしくは新人が早く戦力になれるようキャッチアップを容易にするためってことになりますよね。トラック係数とか属人化とかもそうですが。そうか、ドキュメントが書かれない更新されないのは、その目的が明確化されてないからってのも原因の一つかもしれませんね。なんとなくみんなドキュメントって書いた方がいいって気がしてるけど、何のために書くのかってイマイチ共有されてない。その辺が根本原因かなぁという気がしました。
(2023/10/23追記)
ドキュメントが更新されない原因というか、更新が難しくなる原因を一つ思いつきました。それは今のことをドキュメントに書いてしまうから。今この瞬間のことを記述してしまうから、書かれた内容がすぐに古びてしまう。常に更新出来るならいいんですが、更新できないわけですよね。そして更新されてないのでドキュメントの価値が下がっていってしまう。
今のことを書くというのは、つまりフロー情報を書いてしまってるということなんです。議事録とかはそれでいいんですが、みんなが共通に参照するドキュメントであれば、ある程度時間に対して汎用的になる書き方、つまりストック的な書き方をした方がいいんじゃないかなという気がします。でもこれ、文章の書き方の訓練が必要ですよね。特に気にせず書き始めてしまうと、つい今のことを書いてしまうってのは、とてもありがちなことのように思いますので。
(2023/11/14追記)
ドキュメントにも「伽藍とバザール」モデルって適用できるんじゃないかと思うんですよ。複数ページからなるドキュメントでその章構成もきっちり検討されるドキュメントが伽藍で、担当者がそれぞれ思いついたタイミングで作成される単一ページのメモ的なドキュメントがバザールであると。そういえば最近はあんまり伽藍とバザールって言葉も使われなくなりましたね。
完成すれば伽藍的なドキュメントは凄く役に立つんだけど、なかなか完成しないというのと、一旦完成したあとすぐに現状との乖離が始まって陳腐化しやすいという問題がある。その点では常にスポット対応できるバザール的なドキュメントにメリットがあるんだけども、もちろんどっちかだけで大丈夫ってことはない。両方必要であるし、両方の性質を兼ね備えてる場合もあったりするとは思います。
あれ、伽藍とバザールで何をいいたかったのかな。ちょっと忘れてしまった。思い出したら書きます。ともあれ、ドキュメントにはフローとストックという側面での分類と、伽藍とバザールという側面での分類があるんじゃないかなってことですね。
それとは別にもう一つ。最近テキスト生成AIがすごく進歩してるじゃないですか。もういっそのこと内部的なドキュメントに関してはテキスト生成AIに任せてもいいんじゃないでしょうかね。既存のドキュメントとソースコードを全部テキスト生成AIに食わせてやれば、大半の用途で間に合うドキュメントは生成できますよね。なんなら食わせるソースにはメールやチャットのログとかも入れてもいいかもしれない。Issue とか PR のコメントとかもありですね。なんだかんだ普段のやり取りでテキストを入力することはあるわけで、それを整理したものがドキュメントだとすると、整理する作業をAIにやらせればいいじゃないかって発想です。実際にそこまで仕組み化するのは大変だと思うけれど、先進的な職場ではここ数年のうちに導入されるんじゃないかなぁと想像。
(2024/3/28追記)
ドキュメントの伽藍とバザールで何を書きたいか思い出したので追記します。
伽藍なドキュメントって出来上がるとそれは理想なんですよ。全てを網羅しているし、構成もわかりやすくなっているし。それを読めばプロジェクトの全てが分かる。理想的。ただ問題は、作るのが大変難しいし、変化に追随するのも難しい。言うまでもないことですよね。だからウォーターフォールの現場ではドキュメントの作成/更新にたくさんの工数が割かれていて、場合によっては開発しているよりもドキュメント作成している時間の方が長くなってしまう。って、ウォーターフォールの現場を経験したことがないので、伝聞と想像でしかないのですが。
伽藍は理想だけど実現が難しい。であれば代替としてバザールでもいいのではないかと。つまり、思いついた人が思いついた時に書き散らすドキュメントでも、無いよりはよっぽどいいよねって話です。書き散らかしたドキュメントばかりだと必要なものがどこにあるか探すのが大変ですが、そこはそれコンピュータを使いましょうと。要するに全文検索システムが十分に賢ければ検索には困りませんよね。最近はAIによる要約も実用になってきましたから、書き散らかしたドキュメントを複数まとめて一つのドキュメントにしてくれることもある。また、書き散らかしたドキュメントって陳腐化して現状と乖離しているって問題も発生するけど、そこら辺もAIを使ってうまく解決できるといいかもしれない。
ということで、ドキュメントについては伽藍が理想ではあるけど、その作成と維持には膨大なコストがかかる。であればバザール方式で書き散らかしたものでも無いよりはよっぽどいいのではないかというように思います。私が仕事でもプライベートでもとにかくテキストを書き散らかしているのは、そう考えるからでもあります。このサイトもそうですし、Qiitaとかにも書いてますね。仕事では社内のドキュメントデータベースにとにかくメモでもいいのでなんでもぶち込んでたりもします。もしかしたらそれをゴミをまき散らすなと苦々しく思ってる上司もいるかもしれませんがね。