開発現場で役立つドキュメント作り3つのポイント

概要

この記事では、製品やサービスの開発プロジェクトにおいて、ドキュメント作成を行う際のポイントを紹介しています。

1. WhatよりWhy

これがすべての基本になりますがWhat（なにをやっているか）よりもWhy（なぜそうしているのか）をしっかり書きましょう。

極端なことをいえば『What』はソースコードを読めばわかるのです。中には「ソースコードがドキュメントだ」という人もいるほどです。さすがにそれは言い過ぎですが。

しかし、ソースコードから『Why』を読みとることは難しい。

同じ機能でもプログラムの書き方はさまざまで、ソースコードを正しく読み取ったつもりでも細かい部分まで理解が及んでいないかもしれません。

だからドキュメントでしっかり『Why』を残す必要があります。

それでも多くの人は『What』を書きがち、なぜならそのほうが楽だからですね。

『What』はただ事実を書くだけでよいので「ドキュメントを作った」という実績は確実に残せます。

作業としては圧倒的に楽ですが、そんなドキュメントに意味はありません。

下手をすると、メンテナンス（仕様やプログラムの変更に合わせてドキュメントを更新すること）の仕事を増やしているだけになります。そんな意味のない仕事ならやめたほうがいいでしょう。

『Why』を書いてみると設計意図を明確に表現できない場合や、自分の担当以外の部分を確認しなければならないことに気づくことも多くあります。その結果、作ったプログラムを見直す必要がでてくるかもしれません。

『Why』をまとめることで開発したものの品質と精度は間違いなく向上するでしょう。

2. 図や表を中心に、文章で補足

二つ目は『What』です。『What』はできるだけ図や表などであらわしましょう。

ドキュメント作成が苦手な人の特徴としてすべてを文章で書こうとして「書く作業」になってしまう傾向があります。

文章だけで書くと文脈を読み取らなければならず、自分の知りたい情報を探すことが難しくなります。

将来的に仕様や設計が変わった時も全部読み直して影響範囲を把握した上で更新しなければならないので、メンテナンスも大変です。

書いてる本人は一生懸命のつもりでも、できあがったドキュメントはほぼ役に立ちません。これもまた「書く作業」になってしまっているパターンです。

全体を図示した上で、例外や共通の部分は文章で補足する。この補足する文章が『Why』になることも多いはず。

プログラムの設計というのは、「状態とイベント」「状態とエラー」のように表（マトリックス）であらわせるものが多く、表にまとめることでいわゆる「モレなくダブりのない設計」となります。

もし、どうしても文章で説明しなければならない、図や表で表すことができないとすれば、それはそもそもの設計が悪いのかもしれません、設計から見直すべきです。

設計の美しさは、そのままプログラムの美しさに反映されます。

文章でしか意図を説明できないプログラムは、複雑に絡み合った『スパゲッティプログラム』になっているに違いありません。

3. 詰め込まず構造化し関連付ける

図や表を中心にと言いましたが、ひとつのものに情報を詰め込みすぎないようにすることも注意すべき点です。

関連する情報はひとつにまとめたほうが書くのが楽になりますし、設計した本人なら読み解くことも難しくはないかもしれません。だからといって、あれもこれもとひとつに詰め込みすぎると設計意図を読み取る人にとっては理解が難しいものになってしまいます。

これもまた「作っただけのドキュメント」になる可能性が高い。

詰め込みすぎかそうでないかの境目は一概には定義できませんが、作っている本人がまとめるのに苦労するようであれば、それは読み手にも理解しにくいものになっている可能性が高いと、というのが一つの基準です。

いきなり詳細から入っているので全部読まないとわからないドキュメントは、まず概略（構造や背景）を明確にして、その上で詳細をまとめていくと読み手の理解も進みます。

ドキュメント内で頻出する複数の言葉をひとつにまとめ、参照資料とすることで資料の主従関係を作るというのも良い整理の観点です。

ひとつひとつの資料の役割を明確にし、構造化して参照関係（リンク）をつけていくとよりわかりやすく良いドキュメントになるでしょう。

明日の自分は他人です

ソフトウェア開発におけるドキュメントとは、作った本人以外に設計意図や設計思想を伝えるものです。

明日の自分もまた『他の人』の一人。作った時はわかっていても一日経ったら、週末を越したら、次の開発が始まったら、すっかり忘れているもの。

「なんで、こんな処理にしたの！」「このコメントの意味がわからない！」と過去の自分を責めるということを多くのエンジニアが経験しています。

そうならないために、誰かのためではなくて、明日の自分のためにしっかりドキュメントを残しましょう。

プログラマーの中にはコーディングは好き（得意）だけど、ドキュメント作成は嫌い（苦手）という方も多くいます。

ドキュメンテーションとプログラミングは切っても切れない関係であり、何が必要かがわかっていればドキュメンテーションは難しいことではありません。