ドキュメントは好きですか?

こんにちは。開発本部長の安原です。
訳あって、基幹システムの設計書を見ています。種類も量も多くザーッと目を通すにも心が折れそうです。

f:id:monex_yasu:20211110095409j:plain

ドキュメント断捨離

私自身のことを考えると、日常生活で古い衣類を捨てろと言われますが「まだ着るかもしれないから」ととっておき、今年の夏一回も着なかったシャツがなんと多いことか。。。
 
断捨離とは、

断:新たに手に入りそうな不要なものを断る。
捨:家にずっとある不要な物を捨てる。
離:物への執着から離れる。

なのだそうです。「物への執着から離れる」にヒントがありそうですね。
 

昔のドキュメントは貴重だった

私が社会人生活をスタートさせたころは、フローチャートや表を書けるワークステーション(ゼロックス端末と呼んでいました)は一部の上級SEの人だけが利用することができる貴重なものでした。ドキュメントは印刷され、ファイリングされ、書庫に保管されていました。だから必然的に量は少なく、内容は厳選されていたのだと思います。
だからかどうかわかりませんが、プログラマーはソースコードを必ず確認するように教えられ、設計書は理解を助けてくれるもの、と位置付けていたと記憶しています。重要な設計書は書庫から借りてコピーして手元に置いて何度も見ていました。
 
今はどうでしょうか。
ちょっと人に説明しなければならないことがあると、パワーポイントやエクセルを使って資料を作ってしまいます。前に似たような資料作ったなぁ、と思いながら、新しく書いた方が早いということで私自身ドキュメントを増やしていると思います。全部印刷してファイリングしたらどれほどの量になるでしょうか。サーバーの容量が足りなくなってきた、という別の問題も起こっています。
 

後で見返さないドキュメントは必要だろうか

これって本当に必要なドキュメントなの?というものがあります。
例えば、ほぼSQL文がそのまま記載されているもの。SQL文を自分で書けないプログラマーの為に書いてあげているのでしょうか(汗)。
ウォーターフォール型の開発の利点として、新規に参画したエンジニアがドキュメントを元にすぐに稼働できる、というものがありますから、そういう目的で書かれたものかもしれないです。
今私はソースコードを見ることはありませんが、ソースコードがきれいに書かれていたら、このての設計書を後で見返すことはないのでは?と思ってしまいます。
 

ドキュメントに関する苦い思い出

米国向けの株式のトレーディングツールを日本向けにカスタマイズするプロジェクトがありました。画面の開発は米国の開発チームが担当していました。いよいよユーザーテストが始まる頃になって、ある日本人スタッフが「画面の設計書はないのか?」と言い出しました。開発チームでは、動く画面を作ってユーザーに確認してもらい、フィードバックを得て、それを反映させてまたユーザーに確認してもらう、というアジャイルの開発スタイルをとっていました。ダウンロード型のトレーディングツールの画面設計書をリバースエンジニアリング的に作ったとしても、誰も見ない、誰もメンテナンスしないことは明らかでした。しかし、議論の結果「当社のルールでは設計書が必要」ということになり、プロジェクト外から3名のエンジニアを調達し約半年程度かけて設計書を作成しました。そして、その設計書は誰にも利用されることはありませんでした。
 

ドキュメントが必要な人、ソースコードから理解する人

こんなこともありました。
あるエンジニアは、「このプロジェクトはドキュメントが少ない、開発を中断してドキュメントを整備すべきだ」と言いました。まともな主張です。しかし、プロジェクトマネージャーは、「必要なドキュメントはある」と回答しました。結果的にそのエンジニアは周りのエンジニアよりも生産性が悪く、周りのエンジニアがコードを書き換えることになりました。エンジニアのレベルにより、必要となるドキュメントの種類と量が異なることを知りました。
 

なぜドキュメントが増えるようになったか

システムトラブルが発生すると、ドキュメントに話題が及びますが、問題はドキュメントの量ではなく、観点が漏れているとか、記述が曖昧でどちらにも読み取れる、ということのような気がします。昔の仲間と話をすると、安原さんがやってた時代とは違うんですよ、と言われますが。ドキュメントを作ることが仕事になってしまっていないでしょうか。ドキュメントを沢山書くと沢山仕事をしていることになるのでしょうか。システム開発プロジェクトのコストにドキュメントが占める割合が多いことを考えると、活用されないドキュメントが作られることに心を傷めてしまいます。
 
日常的、あるいは定期的にあまり役に立たないドキュメントを思い切って捨てる取り組みが出来ればいいですが、難しいですね。何か良いアイデアはないでしょうか。