我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか

フューチャーアーキテクト Advent Calendar 2017 の2日目です。 システム設計が大好きで大嫌いな皆さん、こんにちは。 突然ですが、皆さんはどのようにシステム設計における ドキュメント腐る問題 に立ち向かっていますか？ … ドキュメント腐る問題とは、設計時に作成した各種ドキュメントがGoogle Driveやファイルサーバ上で陳腐化してしまい、現状の正しい状態を指していないことです。せっかく新規参画者がキャッチアップしようとしてもドキュメントが真実を示していないという怖いやつですよね。 今まで出会った一番辛いドキュメントは、PJ初期に作成したホワイトボードに書かれたラフスケッチの画像しか無かったところですね。まず字が汚いし、内容も最新版と微妙に異なっていました。新規参画者殺しにもほどがあると、ほんのちょっとだけ恨みました。 いやいや、ちゃんとサボらず整合性を取れよって？サボ

[kamayan1980]

「察して」「コード読んで」が海外勢には全く通用しないので『俺が常に更新し続ける！代わりに俺はコードを触らん！』と言い切ってやるようにしてる。

[rAdio]

ここに「翻訳」の問題が挟まるとさらにややこしくなる…。「腐る」のは仕方ないにしても、どれくらい実態乖離してるのかを具体的かつ定量的に示すことができれば良いのにな、とは思う。

[rti7743]

(2)か(6)じゃないの。実際に動いている実装が絶対正義なはずだ。ドキュメントはそれに追従するべき。なぜなら、"バグ以外"で、ドキュメントと違うからといって問題なく動作している実装を直すことはありえないだろうし

[lifeisadog]

ドキュメントって言った時に、サービス仕様を説明するものと、実装を説明したものがあると思うけど、前者は絶対必要、後者は必要悪みたいな存在。実装の説明を自然言語でする必要があるのかは疑問

[fjwr38]

はい

[SWIMATH2]

6つの選択肢。どれもまあわかるがうーむって感じ

[sylvan_l]

我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか