はじめに

メーカーのコーポレート部門でエンジニア兼スクラムマスターをやっているモンゴルです。

皆さんはドキュメントを書いてますかー？
私は、「ドキュメントは作るけど、認識共有のためのその場限りのものしか作らない。設計書といわれるものも極力作らない。ソースとテストコードが全てやー」という偏った考えを持っています。
私と同じタイプの方もいると思うのですが、一方、「ちゃんとしたドキュメントがないなんておかしい！設計書がこんなにないなんて途中からJOINした人に不親切だ！！」という人にも遭遇します。

今後も、私と異なる考えをもつ方と遭遇した時のために、私はこう思ってるよーを表明しやすくするために、考えを整理しておこうと思います。
案外長文になりそうなので、私が遭遇する問題と本編を分けて書いていこうと思います。
私見が満載ですが、考え方の一つとしてこれを読んだ方のお役に立てれば幸いです。

また、今回はスクラムを導入している場合を想定して書いていこうと思います。

私の思考の前提その1

ドキュメントを作ること自体は問題ないと思います。
むしろ、私自身はUMLとか好きだったりもするので、ドキュメントをたたき台として議論して共通認識を作ることはいいことだと思っています。

「UML モデリングのエッセンス第3版 (Object Oriented SELECTION)」や「エリック・エヴァンスのドメイン駆動設計」でもドメインエキスパートとドキュメントをベースに対話することが重要だと書かれており、私も共感しています。

mongolyy.hatenablog.com

で、だいたい私が揉めるのは次の二点

なぜこのドキュメントがないんだー問題
それを作るのはいいけれど、メンテナンスは誰がすんのさ問題

この二点について思っていることを書いていこうと思います。

なぜこのドキュメントがないんだー問題

「今まで必要性を感じた人がいなかったか、作るスキル、時間、ガッツがある人がいなかったから無い。
気づいてくれて、ありがとう。
あなたが必要だったら、あなたが作ればええやん。チームのタスクとして取り組みたいなら、次のスプリントでバックログに積めばよろしいやん。」

と、冷たいかもしれませんが、思ってます。

ここで考え直す人もいますし、残念ですが指摘するだけで、私の反応を無視する人もいます。
ただ、ここで揉めるのがなんでもかんでもドキュメントを作ろうとする人です。
これが次につながってきます。

それを作るのはいいけれど、メンテナンスは誰がすんのさ問題

作るのは全然Welcomeなんですが、そこそこの頻度で改訂されないと陳腐化するドキュメントです。
改訂されないドキュメントはwikiの検索のノイズになってくるので非常に厄介な存在です。
また、チームメンバーが陳腐化していることに気づかずにリファレンスにすることで、ミスリードされる場合もあります。

スクラムの場合は、頻繁に機能が追加、変更、削除されるので、ドキュメントへの影響は、ウォーターフォールと比べて大きいです。

個人的に、チームの合意を得ずに安易に作っていいものと、安易に作らない方が良いものを分けるとしたら、次のように考えています。

安易に作っていいもの
- 改訂されにくい。陳腐化しにくい。陳腐化しているかもしれないと察せられるもの）
- 例えば、
  - 技術調査の結果報告
  - 採用技術の意思決定の議事
- スクリプトやSQLのチートシート
安易に作らない方が良いもの
- 改訂されやすい。陳腐化しやすい。初見で陳腐化しているのか判断がつきにくいもの
- 設計書のようなかっちりした体裁のドキュメント
- 例えば
  - クラス設計書
  - テーブル定義書（簡易的なER図だけで十分な時がある）

私の思考の前提その2

私自身の育った環境の影響も大きいと思います。

SIer時代、ドキュメントに誤りがあったり、変更し忘れて結果として誤りになっているものの修正に追われた経験
パッケージソフト開発会社時代、メンテナンスされるドキュメントは開発環境構築手順と開発Tipsくらいしかなかったが、みんなソースコードとテストコードを読んで、開発普通にできていた
Webベンチャー時代、同じくドキュメントはほとんどなかったが、Dockerやmigrationなどの仕組みで開発環境構築すら、かなり簡単なものになった

以上より、しっかりしたドキュメントがあった時の負の感情、メンテナンスされるドキュメントがほとんどない場合の成功体験、ツヨツヨなエンジニアだったら、設計書とか読まずともソースとテストを読めばわかるでしょという偏見があるというのも大きいと思います。