山下寛人オフィシャルブログ

オイシックス株式会社 執行役員 システム本部長 山下寛人の公式ブログです。

わかりやすいドキュメント

基本的にドキュメントはいらない派ですが全くないとやっぱり困ります。そのため開発時にドキュメントを書くことになります。しかし意外とポイントをおさえたわかりやすいドキュメントを書くことは難しいものです。

ドキュメントを書く理由はレビューのためと保守のためです。特に保守が重要です。開発した人でない人がトラブル対応をする場合があります。数年経って作った人も忘れたころにトラブル対応したり機能拡張したりすることもあります。そんなときにソースコードだけでは読み取れない情報がドキュメントになっていると役に立ちます。具体的にはその機能の目的だったり実装の意図といったようなところです。

なぜ難しいかというと、書く人は自分が知っていることなので他の人が何がわからないか予想しながら書かないといけないからです。ドキュメントがうまい人はこの予想が上手いのでわかりやすくなります。そういう訓練はしたほうがよいでしょう。

もう一つのアプローチとして作る人が書くのをやめてもいいかなと思っています。全然知らない人が開発した人にヒアリングします。説明を聞いてわからないことは質問します。そして聞いて理解したことをwikiに書きます。こうすれば客観的にわかりやすいよいドキュメントになるのではないかと思います。

これはできた後の話で開発前のレビューについてはまた別です。こちらはドキュメントというより「仮組み」のほうがいいと思います。画面、コードとも、思いつくままにガッと書いてレビューを受ける。レビュー結果を踏まえて隅々まで作り込む。いわゆるプロトタイプですね。