分かりやすい仕様書を書くために気をつけたい5つのこと

今回はドキュメンテーションです。ある程度プログラマとして経験を積むとドキュメントを書く機会が増えていくかと思います。しかし、ちゃんとしたドキュメントが書ける人というのは意外と多くありません。ちゃんとした、というのは読み手が十分に理解できるドキュメントということです。

そこで今回は分かりやすいドキュメントを書くために注意したい事柄について紹介します。

冗長的な書き方はやめよう

最もダメなドキュメントは正確性を求める余り、読みづらくなる文章です。○○画面、○○ボタン、○○リンクなどとにかく説明調であったり、“○○画面にて○○ボタンを表示する。その後、○○ボタンをクリックすると、○○画面にて○○を表示すること”などと読んでいてやたら疲れる文章を書いてしまうことです。

これでは読み手がコンピュータのようになります。かといって読み手は半分程度しか理解できないため、バグが入り込む余地が多くなります。つまり文章の背景にある「なぜ」が理解できないために文章をそのままコーディングし、その結果として条件の漏れが発生するのです。文章の正確さより、まず読み手がちゃんと知解できる文章を心がけましょう。