設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ

はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、

[dh16t]

“「あとでドキュメントを直す時間を取ろう」は大体、そんな時間は来ません。” ほんとこれ。プロセスに組込まないと無理。組込んでも蔑ろにされるけど。あと表は辛いから、複雑な表は極力書かないか、別ファイル。

[paradisemaker]

必要な要素全てを満たした設計ドキュメントツールって未だに無くて、どうしたもんかと毎回悩む

[nakamura-kenichi]

どういう訳か治具としてのアプリ書く文化があんま無いんよなあ。プログラマーとか便利なコード書いてナンボやのに、余所のツールそのまんまばっかで、自分らにとって便利なアプリ書いてる現場がホンマ無いんよなあ。

[mezamashi0540]

根っこは単純に時間の問題だと思う。余裕があるほどコードやテスト、ドキュメントがよくなる。プロジェクトが占有した時間に対してどれだけの余裕をもたせたか、マネジメント的アプローチが必要なのではと思っている

[ackintosh]

ドキュメントをちょっと直したいだけのときに、featureブランチ切ってレビューに出すのは結構面倒（マメにドキュメントを更新する派の感想）

[a-know]

“結局人で管理する部分が残るのであれば、陳腐化しちゃいますよね”

[iselegant]

Doc管理をコードリポジトリに寄せるとエンジニアリングとDocメンテに距離感が縮まるの期待はできる。ただ、結局は腐らせない、というオーナーシップ(強い心)が必要なんだよな。

[kekera]

なんかツールとしても記法としても統一されてないよね。あちこちの開発現場で一長一短あるのを良いように雰囲気合わせて使ってる。

[hogeaegxa]

ツール云々より、一度客にリリースした後は人も減ってドキュメントへの興味も失って、開発プロセスからドキュメント更新も外れて、メンテが仕事の評価外のボランティア活動になるのが腐敗の原因の全てな気もする。

[chi-bd]

結局、初期開発時の「こう作る」フェーズでしかメンテされないからだよね。管理方法やツールの問題じゃない

[tmatsuu]

うっ。ですよね。

[nabinno]

Pj/Pd単位でまとめればJira/Confluenceで自然と整理されそうだが、それではダメなのか?

[honma200]

こういうのをちょちょちょーってやってくれるAIでもできりゃあなぁ。ちなみに書くだけならなんだかんだでexcelが一番楽でノートアプリって思うようにかけない

[SundayIsEveryday]

組み込みでウォーターフォールで開発してるから、ドキュメント変更してからコードを変えてる。ドキュメントも構成管理しないとプロセス違反だし、客先監査で怒られる文化だから、ドキュメントが腐ることに驚いた。

[lwix]

海外のいろんなWebサービスを見ていてふと、各種マニュアルがテストシナリオを兼ねているんじゃないかと思った。例えばユーザーマニュアルは検収（リリース前）テストのシナリオそのものなんじゃないかと。

[Andrion]

wikiはマジで腐る。次点でGit管理のドキュメントも腐りやすい、あとnotionみたいな修正したらすぐ反映されるような共有ドキュメントも腐る。結局Wordで20231102_提案版とか書いてるやつの方が腐らないという現実

[atsushifx]

ドキュメントといっても、誰向け、レイヤーなどで十把一絡げにはできないのだが。PlantUMLやMermaidJSのようにテキストから図を生成できるようにして、生成AIに任せられる方がいいとおもう

[ghostbass]

コードは意図を反映しているが意図そのものを表現しない以上コードから意図を正確に抽出することはできないのですよ。

[nemoba]

OSS見りゃ分かるんだけど、ドキュメントのメンテ工数は、コードより多いのよ。そんなメンテコストが成立する世界は無いのだ。その認識からだと思うよ

[PrivateIntMain]

腐ったドキュメントってその時点のコミュニケーションでは不要になっているはずだから一度墓に埋める(必要になったら復活させる)とかでもいいのかもしれない。

[kenichiice]

「Wiki管理は高速で腐っていった」

[roshi]

この辺の話、「ソースコードにコメントを書く」が最適解だと思ってるんだけど、なぜか書きたがらない層が一定数いるんだよなー。

[tettekete37564]

TOCはGitHub actionsで自動生成取り入れてみた事あるけど、不要なコミットがやたら増える+サブディレクトリのパス全部記述する必要がある=新たにディレクトリ掘るたびにアクション編集が必要になる、で現実的ではなかった

[htnmiki]

腐る＝誰も見ずに開発は進む、つまりそのドキュメントは本当に必要なのか？という根本を考えるべきでは。絶対に腐らせたくないならドキュメントのメンテしないと実装させないくらいの強いルールにすればいい。

[s2kw]

github.wikiをobsidianで作成したvaultの保存リポジトリにしている。プラグインも同期されるので便利。基本、ドキュメントはpull,pushのみで運用してる。

[dec123456789]

開発工程ごとに作成•編集するドキュメントを規定してレビューで一緒にチェックで終わる話じゃないの？Gitとかツールとかってそこが決まってからする話では？SIerの会社みたいだけどSIなら基本中の基本では？

[daira4000]

ファイルサーバにいつ作ったかわからんエクセルがあるのやめたいけどなかなかね

[ls-ltr]

私もドキュメントの陳腐化は課題。gitlabを導入し始めたが、既存のExcelをマークダウン化も色々あり断念中。MRが来た時はTortoiseGitでエクセルの差分を抽出して暫定対象中。wiki問題も同意。

[blueroom555]

可能な限りドキュメントを減らし、本質的なものだけに絞り込むべき。そしてできるだけ人力で頑張らない。

[tsukitaro]

ドキュメント腐る問題：設計時に作成した各種ドキュメントがGoogleドライブやファイルサーバ上で陳腐化してしまい、現状を正しく反映していない(「現状の正しい状態を指していない状態を指します」←残念な文章)

[Shinwiki]

パクりのにおいを感じる…こんなの10年以上前から提唱されてたはず。ドキュメント管理への応用

[qaliinfo20]

いろんなツール使うと数年後にツール自体が化石になり、誰も触れなくなるんだよな。そもそも一旦チーム解散すると人もいなくなるし。ツールの使い方とルール覚えるだけでストレス

[everybodyelse]

先にドキュメントのPRを書くドキュメントファーストなのいいな。確かに設計はそこである程度見れそう。

[binary343]

物が出来た後の設計書は自動生成物にしたい

[hiroshe]

ChatGPTでコードから生成できないんだっけ