最低限のドキュメントを残すこと

現状の仕様などがドキュメントとして残っていないために、どのような問題を引き起こすことになるか、考えさせられる機会があったので、自分の中で考えを整理しました。当たり前のことを書いてるだけですが、できてないことがあるのが現実です。

結論としては、最低限のドキュメントは書けということなのですが、個人的に痛感させられるできごとがあったので、書き始めたら長くなってしまいました。

人間の脳は、記憶に入った内容の重要度に応じて、記憶の奥にしまい込むか、完全に忘れてしまうかのどちらかを行っていると思う。記憶してからの経過時間がある一定期間内であれば、まだ記憶から簡単に取り出すことはできるかもしれない。でも1ヶ月経ったら、その記憶した内容をきちんと覚えてる？もしくは1年経ったとしてもきちんと覚えてる？覚えてないはずです。大ざっぱな記憶でよいなら思い出せるかもしれない。でも実際には、細かい内容で思い出す必要があった場合、記憶から全部引っ張り出すことはできず、他人の記憶や自分が書き留めたメモなどといった別の記憶媒体の力を借りて思い出すことになるんじゃないかと思う。

今やウェブサービスは、どんどん新しいサービス、新機能を実装しないといけないんだから、ドキュメントなんてもの不要だし、細かい内容はプログラムのソース内にコメントを書いておけば、後から思い出せるよ、なんて言う人もいるかもしれない。でもそのサービス、機能って、誰が主導して考えていくの？サービス設計者＝開発者であれば、話はまた違うのかもしれないけど、実際には、経営者であったり、開発者とは別に存在する(ユーザの視点に立つ)サービス設計者だと思うのです。

そのような人たちはプログラムのソースを見て、内容を理解してくれるのでしょうか？できないですよね。だから、ドキュメントがない場合には、開発者が何度か彼らに説明する必要性が出てきます。そんな時間を何度も費やすぐらいであれば、きちんとしたドキュメントを作るべきです。

ただし、先ほどいった新しいサービスや新機能をウェブサービスとしてユーザに提供する必要があり、なおかつ自社で開発をしている場合には、すべての網羅した事細かなドキュメントを作ることは、実際には難しいでしょう。仮に作ったドキュメントがあったとして、それらを見返しつつ、新機能などが実装された場合にきちんとアップデートし続けることは難しいはずです。

少なくとも以下に示すようなドキュメントは必要かと個人的に思っています。

• ユースケース図
• 画面遷移図
• 機能一覧
• システム構成図
• システム全体の枠組みとなる設計ドキュメント
• クラス図
• ER図

実際には、これだけでは足りないとかあるかもしれませんが、サービスのリニューアル、もしくはメンテナンスを行いたい場合に、現状を簡単にきちんと把握できることが大事だと思います。

仮に先ほど書いた内容ができていない場合、将来どうなるか考えてみましょう。ありそうな内容としては、サービスの新機能追加、システムメンテナンス、サービスのリニューアル、システム構成の見直しなどが挙げられます。

どれもきちんとしたドキュメントがないと、上手にそして効率的に作業を進めていくことができないです。このまま何も考えずに作業を進めていくと、

• 設計変更に伴う影響度を見積もれない
• 設計変更に伴う影響範囲を把握できない
• 小さな機能変更でも一度ソース内の記述内容を確認する手間がかかる
• 正しい動作をしているのか検証が行えない
• システム障害などを引き起こした問題を洗い出すことが難しい
• 既存ライブラリと似たライブラリが複数でき、プログラムがスパゲッティ化する
• 現状の動作がソースもしくはユーザ視点で動作させた内容でしか把握できないので、リニューアル作業が進まない

といった問題にぶち当たることが目に見えてます。

結果として、サービスおよび機能を効率的、かつ効果的にユーザに提供することができず、むしろ既存のサービスを維持することで精一杯となってしまい、袋小路に追いつめられてしまいます。もしくは最悪の場合、サービスの維持すら困難になってしまうかもしれません。

では、これらの問題を解決するにはどうすればいいのか、考えるまでもなく、きちんとドキュメントを作成し、現状をまずは把握することでしょう。これには、時間がかかるでしょうし、場合よっては困難を極めるかもしれない。今まできちんと何もやってこなかったツケが、今になってやってきたと考えてやるしかないでしょう。何よりも躊躇して、前に進まないよりも、踏ん張り所だと思って頑張るしかないのです。