ドキュメントを書かないことは「負債を生む」ということ - Qiita

本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から

[morucy]

書いたドキュメントが全くアップデートされず、その古い情報が逆に混乱の元になることもあるので、ただ書けばいいと言うものでもないのが厄介。

[rityel]

エントリに上がるqiita記事にマジで苛ついてきた。説教ポエムはてめーんとこの会社の中だけでやれ。

[kazuppo01]

ドキュメントのメンテに対するブコメが多いけど、ドキュメントを書かないよりは、古くても書いてあった方がマシ。古いのがあれば差分をアップデートすればよいので。 書く習慣がないことはヤバいと思った方が良い

[kakei-akihiko]

こういう考えの人、書いて無駄になったドキュメントのことは考えてない。「将来この情報が必要になるだろう」の予測で残しても大半が読まれず更新もされない。ドキュメントが必要になった人が残すのが現実解。

[vegnpomn]

コードからは歴史の一端や業務知識が抜け落ちてるので、それだけAIに食わせてもコードリーディングにしか使えなくてドキュメント替わりにはならない。形式がAI用か人用かは変わっても、書き続けるのは変わらなそう

[JULY]

主張に異論は無いんだけど、どうしたら有用なドキュメントが残せるようになるか、に対して銀の弾が無い。「有用なことだからやりましょう」では解決できない。

[Eiichiro]

なぜそうなっているのか？を残すのはとても難しい。まだ機能要望はなら経緯を残せれば良いが、実装と要望のトレードオフがある場合は余計にむずかしい。 全体像把握系の資料は陳腐化しにくいので、作ってる。

[gabari]

説明するドキュメントは不要、なぜそうしたかを書くドキュメントは必要

[spiral]

ここに書かれている内容ではドキュメンテーションの有用性や、どんなドキュメントが有益なのかわからない。この内容で「だから書け」は厳しいだろう。

[dot]

書きっぱなしのドキュメントも充分に負債なので、現在のリソースでメンテできる分を作るしかないし、それ以上に必要なら、まずそのリソースを確保する必要があるのだ。

[tmatsuu]

せやな。自戒

[pmint]

何のドキュメント？意味不明。最初のドキュメントは顧客が書くものだし。ドキュメントが何なのか知らずに書いてるんだろう。実装以降にできるドキュメントは、コードで書きましょう。"メンバ"…笑。仮名遣いが古い。

[aroechan]

「ドキュメントは正しくなくても運用されるが、コードは正しくないと壊れる」これがすべてだろ/Document As Code の精神でコードを書かないのが悪い、というかそこまで到達できているスキルのある人が足りない

[ducktoon]

書くなら最低限テキストファイルをGitHubで管理してくれ。Excelに書いて共有フォルダに置かれても誰も読みません

[shingo-sasaki-0529]

AIの登場によって WHAT とか HOW はもはや人間がドキュメンテーションする必要性は失われていきそう。ただ WHY は依然として必要そう。意思決定の背景とか。

[koogawa]

“何故なら、ドキュメントを書くべき人は、必要な事項を知っているから” これは本当にそう…

[tym1101]

作成周知更新、ができないと作ってもあまり意味がない

[okinawazenzai]

負債というかはリスクだよな、普通に定年退職もあるし少子化だし、若返りの薬が開発されるぐらいしか解決策ないのかもしれんねw AIで法令改正の時入れたコードの意図とか読み取ってくれると思えんけどなー

[Watson]

真理

[w1234567]

書いたドキュメントが混乱の元になるから書かないとか言ってる奴は情報伝達の手間を他人に押し付けてるだけだよ。リモートワークなら書かないとプロジェクト回らないしとりあえず書いて問題があれば直してくれ、頼む

[hiroshe]

何をどこまで書くべきか、加減が難しい。書き始めると夢中になってつい書きすぎる。手順が自己目的化しがち。

[yo_waka]

その瞬間の経緯でもいいからあることで助かることはある。メンテされてないことよりもそもそも無いことが問題になることの方が多そう

[rokusan36]

セーブポイント

[tacamula]

網羅的なドキュメントよりも動くコードの方が価値がある。理想はコードから思想が読み取れる状態。それができないのは技術的力が足りてない。って理想を目指して不足をドキュメントで効率的補うバランスを目指すべき

[fa11enprince]

更新されないのが問題というのがあるけどないよりマシでそれを100%信用することはない。とっかかりが欲しくて、詳細な説明ではなく大きな設計の部分、ほぼ変わらない部分のドキュメントはあってほしい。その経緯も。

[diveintounlimit]

書いたドキュメントも負債化するが、無いよりは100倍マシ。やらない理由を考えるのはとても簡単だ。やるよりやらないほうが、常に「今は」楽だから。

[inusuki2023]

txtでメモだけでもいいんだよ。それすら残さない人間は「自分がいる時だけ回ればいい」と未来を考えていない連中か、「情報を自分が握っている」と優位に立ちたい自己中ばかり。

[jintrick]

コメントなら書くけどね

[cowbee]

最新の事実はソースコードやスキーマから、経緯はコミットログに紐づくチケットやチャットリンクから生成AIが拾ってCIでドキュメンテーションしてくれるツール待ち

[Karosu]

スタンドプレーからチームワークのプロジェクトならドキュメントがいらないけど、チームビルディングありきのチームワークの場合はドキュメントないと間違った方向へ行く