社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog

はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた

[y_as]

“社内ドキュメントはなぜ更新されないのか？”そんなもん評価されない（報酬がない）からだよ。カイゼン一件につき500円みたいな工場が話題になったことあるけど同じように報酬出せば更新の奪い合いになると思う。

[Dursan]

日本にPDCAってマジで少なくって、PDPDPDPDPDPDPDとしかやってない。

[jtw]

その価値を経営者が認めていないから更新されないだけ。稼働も評価（給与）も与えずに、なぜ更新されると勝手に思い込むのか。

[Flume]

上位コメにあるようにやっても評価されないのと、あとは自分のタスク以外に興味無い（チーム全体の生産性考えない）人が殆どだからじゃないかな。

[ntstn]

こういうのこそAIにやってもらいたい

[bufferings]

おもしろかった！僕の中ではプロジェクトのときに書くドキュメントと、その積み重ねとして更新し続ける最新仕様ドキュメントがあるんだけど、似た感じだよね。言葉の定義も好きだな。嬉しい。

[htnmiki]

厳密には「評価されないから」ではなく「参照されない」からかなあ。使われないものはメンテされないし、それで回ってるなら不要なドキュメントだったということ。

[WildWideWeb]

問いと答が釣り合ってない印象。そう思ったのは文脈が与えられてないから。「自分がそれをするインセンティブがないとみんなが思ってるから」という読み手が一応思いつきそうな答とは異なる前提での問いかけだった。

[pixmap]

ドキュメントもGitで管理すればいいだけでは？ドキュメントはミュータブル、イベント（コミット）はイミュータブルって自然に分離できるよ。「なぜ更新されないのか」の直接の答えにはならないけどね。

[manaten]

ドキュメント類、ゲームのwikiが本文でリソース情報、更新情報でイベント情報がきれいにまとまっており、更には関連単語という形でリレーションもされていて非常に読みやすいので、どうにか真似できないかと思ってる

[okbm]

仕様書をgithubで管理して差分を見ながら開発するのめっちゃ楽だった。書く人のコストめっちゃかかるけど

[endo_5501]

“より俯瞰的なドキュメントが必要だと感じたら(かつ、まだ力尽きていなければ)、それらをまとめてPRDやDesign Docsとしてドキュメント化する” そう、「力尽きてなければ」

[razokulover]

ちゃんと管理する責任者を作らないからだとドキュメントライティングの本に書いてあった

[mallowlabs]

“ストック情報の中にも、実は「ミュータブル(可変)な情報」と「イミュータブル(不変)な情報」の二つがある”

[tmatsuu]

うっ。はい。

[arajin]

“まず小さな意思決定をイベント情報としてドキュメント化し、次にそれらの積み重ねを参照することでリソース情報やより抽象的なイベント情報をドキュメント化する”　課内のwikiつくって、似たようなことやってた

[tsubosuke]

更新されないと業務的に困るものなら更新せざるを得ないし、更新されないならそれは更新必要ないってことなのでは。

[codenote]

GitHub repositoryでドキュメントを管理するのオススメです🧑‍💻

[sho]

GitHub上でPRベースでドキュメント管理してれば自然とこうなるじゃん

[sippo_des]

pdcaのcてcancelですので、皆さんご存知ないと思いますが、、 それはそれとて認知度の低い資料の多いとこよ

[hetarechiraura]

重要な仕事だと思って更新したけど評価されなかった経験があるからこそ、こういう反応が多いんじゃないっすかね…😇／そもそも俺の人生にとって勤労そのものが重要じゃないんだが？？？誰に、何にとっての重要？

[MacRocco]

メモ

[sp_ice]

良いコンセプト！ドキュメントを統制する人が不在の現場を経験したが、必要なものが最新化されてないから付け焼き刃で作った資料だらけになってて辛かった。参照される資料は最新化されると思ってるなら甘い。

[tkys0628]

“個別の意思決定ごとに、「承認された日」「背景」「決定されたこと」「決定による影響」のみをドキュメント化する より俯瞰的なドキュメントが必要だと感じたら(かつ、まだ力尽きていなければ)、それらをまとめてPRD

[nunulk]

"なぜ更新されないのか？"―要らないから。とはいえ、仕様を決めるときは Slack、会議では Notion に議事録を取る、チケット管理も Notion でやってリンクを張る、とかがいまんとこマイベストかな

[kent4989]

残念ながら共感は出来なかった。ただうまくいっていないことだけは確かなので、何かの突破口は見つけたいところなんだけど。

[takilog]

更新されないドキュメント、いらないんじゃないの？

[mujisoshina]

一般に社内ドキュメントは更新されるべきなのか？を考えると、放置されているものは使われていないから更新の必要もないのが殆どだと思う。まずはドキュメントを有効活用して参照数を上げる取り組みが先なのでは。

[otihateten3510]

イミュータブルドキュメントの考えはいいと思う。良い提案。

[PrivateIntMain]

今どうなっているかも大事だけど、それ以上に「これはどうあるべきものか」「そうなっていないなら何がネックなのか」の2点だけでも押さえているとだいぶ違う。

[mmaka2787]

議事録は集中して聞いて内容理解しないと書けないしWFは全体と細部理解しないと書けないし、どちらも作成に技術が必要で、かつ、なくても殆どの場合一定程度まで問題が生じないのでコスパが悪い。

[REV]

自分の職場では、「ドキュメントを読んで仕事をする」より、「もしもし！わからないんだけど！教えて！教えて！」と相手が音を上げて「じゃあ、私がやります」と仕事代わるまで電話鳴らす方が本人には合理的なので。

[natu3kan]

コールセンターのナレッジみたいに仕事の度に回答の根拠として見て使うの必要で、間違いや古い情報に気が付いて更新せざるを得ない業務でもないと、更新しなかったことに責任が生じにくい上に更新コストが厳しい。

[sds-page]

なんかの機会でチェックした時に更新してなかったら怒られるけど普段は誰も見ないし定期的に更新しても評価に繋がらない。手法を云々する以前の問題

[syu-m-5151]

具体的な施策に落とし込んで継続して向上させ続けるのが本当に難しい。なぜなら、社内ドキュメントと読むだけの人は年々増えていくので…

[ledsun]

理由は簡単、ドキュメンテーションの訓練を受けてないから。ほとんどの人は、一般的な技術文書を書く訓練も、その会社または組織でどんなドキュメントをどうやって書くのかも説明を受けた記憶がないはず。

[RXRHsZcJ6xnGXZR8TEZA6hAxzRd3mkD]

ドキュメントにいいねボタンとコメント欄つけて社員同士でレスバさせれば盛り上がるで。なおドキュメント更新はされない模様

[chikurou]

レビュー対象に入ってないから。

[onesplat]

…で？具体的にどうすればいいの？え？終わり？

[NikugaTabetainoyo]

ほー