読者です 読者をやめる 読者になる 読者になる

四十三庵

蔀の雑記帳

ドキュメントに関する考えの変遷

IT

SIerにいる新卒が、三年間でドキュメントというものに対して、どう考えが変わっていったかを書きます。

一年目

うわ、なんでドキュメントないんだこのシステム。
わかるわけねーだろ。
残せよ。ドキュメントを。
わかる奴がわかればいい、じゃないだろ。
人の移り変わり激しいんだからさ、この業界……

しょうがないからひたすらソース読むか……

二年目

このシステム、ドキュメント充実してるけど……
100ページに迫る詳細設計書って誰が読むんだ?
何のために存在するんだ?
もはやこれソースコードと同じじゃないか?
要件定義書もなんかグダグダ書いてあるし……
しかも全て網羅されてるように見えて、メンテナンスされてないから、微妙に最新状態と食い違ってる……

ソース読んだ方がはえーわこれ

三年目

・ドキュメントは必要最低限のものがあればいい。
 余計なものを書くな。
・「必要最低限」の定義はけっこうケースバイケースになる。
 CMMIとかPMBOKとかISOとか一応基準らしきものあるけど、
 そういうのに従うとムダなドキュメントが大量生成される現場が生まれる。
・ドキュメントの管理コストはけっこう高い。
 特に規模がデカくなればなるほど。
・「ドキュメントがどこにあるか」をチーム全員で共有できるのが大事。
 (なんなら会社全員)
・ドキュメント管理ツールは時代とともに変わりがちで、移行は厳しい。
 ツール自体はGithubだろうとWikiだろうとファイルサーバーだろうとクラウド上だろうと
 Notes()だろうとその他グループウェアだろうとなんでもいいんだけど、
 時代とともに置き場を簡単に移動できるようにしなければならない。
・また、簡単に検索がかけられるようにしておかなければならない。
・AIが「あなたの探してるドキュメントはこれですね?」と提供してくれる時代が来るのかもしれないが、
 個人的には、そのために我々のような人間が働いているんじゃないかという気がする。
・ドキュメントがあっても読み解けないレベルの人しかいなくなると、「ドキュメントを解説するためのドキュメント」みたいなのが無限にできるので、
 チームのスキルレベルはある程度の下限を保たないといけない。

今の思い

たぶんこれからも変わらないであろう事項を現段階でまとめる。

・ドキュメントは銀の弾丸ではないので、結局は誰かがソース読まないと運用保守できない
・ドキュメントは本当に必要なものだけを書くべき
・ドキュメントの管理ツールは時代によって変わるので、簡単に移行できるようにしておく
・ドキュメントで全部解決はできないので、教育が重要
・必要十分なドキュメント作成+全員が簡単に見つけられる場所に置く+要員教育が正攻法っぽい
(了)