前回はドキュメントの重要性について書きました。
今回は今までにあった事も含めて、ドキュメントの重要な点のさらに細かい所を説明します。
ドキュメントを作成するにあたり、誰に向けて書くかは重要です。
既存の知識があるか分からない方に向けて手順書を作成する場合は、基本や用語から作成することで、確認の手間を減らせることが出来ます。
以前あった事件では内部向けに書いた設計書が外部に展開されました。そこで認識の違いが発生し、炎上しかけました。
その件に関しては、作成するのであれば、細かい部分を省き、見やすいフォーマットで要件を記載する必要があります。
コードを書く方にはよくある話ですが、処理を修正した後、コメントを修正しないといった方がいました。
処理や概要をわざわざ記載したのに実際の動作が異なり、確認に時間がかかっていました。
逆に分かりきったものにコメントすることも無駄です。
よくある修正履歴も「◯月◯日修正しました。名前」だけ書くなら書かない方が良いです。今はGitで管理することがほとんどなので、書かなくても分かります。
入会申込
ログイン
