ドキュメントが更新されない問題 - Konifar's ZATSU

むかし、この国が深い森におおわれ、そこに太古からの神々がすんでいた頃から語り尽くされているドキュメントが更新されない問題について雑に書く。 実態が変わったのにドキュメントが更新されない問題はいつどの時代も絶えない。これにいちいち憤りを感じるのは不幸になるだけなので、何かしら対処を考えておかねばならない。パッと思いつくのは次のようなものだろうか。 使う 使わないから更新もされなくなる。定期的に使われるように設計して、そもそも使わない場合は消した方がいい いっそ参照回数が少ないドキュメントは自動でアーカイブしちゃうみたいな硬派なスタイルの方がいいのかも 詳細に書きすぎない 細かいところを書きすぎると保守できない。骨組みだけ大事にして、細かいところはフロー情報として分けて書くのがよい 管理者を置く ちゃんと更新されるようロールを作る。属人化しないようにロールを引き継ぐ設計も必要 個人的にはあんま

[sgo2]

読みたくなるのは、ソースの意図が分からない時なので、ソースやテストコードのコメント/リポジトリのログにこのドキュメントを読めと書いておいて欲しい。

[luccafort]

自分の理解では…という感じだけどドキュメントメンテ問題は「読まれない」が最大の問題だと思うので読まれるようなフローを整備するのが一番いいんだろうなと思う。そのうえで使われるために書きすぎないようにする

[hkawaras]

詳細に書きすぎない分かる。変更箇所生まれたら変更するのしんどいときがある

[turanukimaru]

最近は「自分が何を作ってるのかわかってないのでドキュメントを書かないし更新しないスクラム」ばかりに参加してる。プロダクトオーナーがプログラムもドキュメントも主体的にまとめていかないといけないんじゃ…

[cl-gaku]

使うしかない。使わないドキュメント書く時間の虚無感は異常

[udofukui]

知見ありがとう。そしてもっと色んな人出してほしい。

[ema_hiro]

ドキュメント警察ともいうべき属人的筋肉運用に頼りがちなんだよなぁ。。。

[spfrv72010]

ウォーターフォール式の開発時と、単体製造後に必要となる設計文書って異なると思う。前者は大概処理手順とか記述するけど、後者で目的と諸元だけ知りたい時のノイズだし、変更時は文書とコードで二重の手間になる。

[yogasa]

インセンティブが弱いんだろうなあ

[morimarii]

普段使わなくてもシステム移行時に参照が必要だったりするからなあ。そういうのがないと意図不明なロジックや設定が呪文や石碑のように受け継がれていく。。。

[to4iki]

“詳細に書きすぎない” わかりみ

[lets_skeptic]

ソースコードのコメントには概略とwikiへのリンクを書く

[nlogn]

この問題を解決するのがクヌース先生のWEBシステムなのだが、プログラマの多くは文章が書けないため広がらなかった。

[alphaorange69]

キーワードが時間とともに迷子になるというか、、難しい

[kaakaa_hoe]

使うのは勿論そうなんだけど、初めて読む時の感覚は1人一回しか味わえないので、そんなに人間いないよねとなりそうな。主管付けながらEdit on GitHubとかで提案しやすくするのが関の山。

[blackblueash]

結構更新してるよ。

[strawberryhunter]

プログラムを読んで自然言語で要約してくれるプログラムがあればいいんじゃね？自然言語の要約よりよっぽど簡単な気がするので誰かチャレンジしてください。

[miki3k]

知る限り20年以上前からずっと言われ続けている

[shinobue679fbea]

使う。これに尽き申す