開発ドキュメントを分かりやすく書くための方法を「開発ドキュメントの書き方」に公開しました。以降はこちらもご覧ください。
私は以前チームで開発していたとき、よくドキュメントを書いていました。ドキュメントを書くと「仕事をした！」という気持ちになれました。ただふりかえってみると、そのドキュメントは誰にも読まれなかったし、本業であるソフトウェア開発の進捗がわるくなっていた、ということがありました。
あらためて、ソフトウェア開発におけるドキュメントとはなにか、なにを書くべきか、あるいは書くべきでないかなどについて整理してみました。ドキュメントを書くときの参考になればうれしいです。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
対象となる読者の方
この記事は個人やチームによらずソフトウェア開発に携わっているエンジニアの方にとって参考になると思います。まず全体をざっと読んで概要を把握しつつ、実際にドキュメントを書くときに見る、というような読まれ方を想定しています。
ソフトウェア開発におけるドキュメントとは
この記事ではドキュメントの書き方について書いていくのですが、ここでいうドキュメントの定義についてまず整理しておきます。先に結論をいうと、この記事ではアジャイル開発における「開発や運用に必要なドキュメント」について書きます。
プロダクト開発の方法としてはアジャイル開発が主流となっていますが、「アジャイルソフトウェア開発宣言」ではドキュメントについて次のように書かれています。
包括的なドキュメントよりも動くソフトウェアを
このこともあってか、アジャイル開発の現場によってはドキュメントをあまり書かない方針のところもあるようですが、この宣言はドキュメントに価値がないといっている訳ではないんです。
この宣言でいう「包括的なドキュメント」とは、角谷信太郎氏の「第4回 ドキュメントを大切にする: アジャイル開発者の習慣」によると、次のように示されています。
要求定義→設計→実装→テストといったいわゆる「開発工程」の区切りに作成されるドキュメントのことです。仕様書や外部設計書、詳細設計書、テスト仕様書、テスト実施報告書などがその代表例です
つまりウォーターフォール型の開発手法に見られるようなドキュメントは減らすべきだけど、それ以外のドキュメントは依然として価値がある、といっています。
ソフトウェア開発におけるドキュメントの種類
ここでいう価値のあるドキュメントは、たとえば次のような種類のものがあります。
- ソースコードやテストコードなどの「動くドキュメント」
- GitのコミットやPull Request
- ユーザー向けのドキュメント
- 開発や運用に必要なドキュメント
これらのドキュメントを継続的につくっていくことが、ソフトウェア開発には重要になってきます。この記事では、とくに「4. 開発や運用に必要なドキュメント」について書き方を書いていきます。
また、この記事では文章技術のようなテクニックの話は書きません。これについては「開発ドキュメントの書き方」で書いているので、参考になればと思います。
なぜドキュメントを書くのか、あるいは書かないのか
ドキュメントにはいろんな種類のものがありますが、基本的な目的はソフトウェアの価値を高めるために書くと思います。ソフトウェアの価値を高めるドキュメントとは、つまり次のようなものであるべきだといえます。
- それが必要なときに
- 必要なタイミングで
- 必要最小限のもの
必要なときにドキュメントがないと、必要な情報を得られず、開発に支障が出てしまいます。たとえば環境構築のときなどです。逆に必要としている人がいないドキュメントを書くことも、ソフトウェアの価値を高める時間を減らしたという意味でよくありません。
またタイミングについては、遅すぎるのはもちろん早すぎてもよくありません。ドキュメントを書くのが早すぎると、変化の早いアジャイル開発では必要なときに前提が変わっているかもしれません。
ドキュメントは充実していればいいかというと、しすぎるのはよくありません。必要以上の情報は読むコストがかかりますし、変更の多いアジャイル開発においてはドキュメント自体の保守コストがかかってしまいます。
ドキュメントは開発に必要なツールではありますが、ソフトウェアの価値を高めるという目的と、そのためにどうドキュメントを書くかは抑えておく必要があると思っています。
ソフトウェア開発におけるドキュメントの書き方
では、どのようにドキュメントを書けばいいのでしょうか。開発や運用に必要なドキュメントには、たとえば環境構築やアーキテクチャ設計の意図についてなど、いろんな種類があります。ここでは基本的な書き方について整理します。
ドキュメントを書くときは、次の4W1Hを意識して整理するとよいドキュメントにつながります。
| 順番 | 項目 | 説明 |
|---|---|---|
| 1 | What | このドキュメントはなにを示すのか。あるいはなにを示さないのか |
| 2 | Who | 誰のためのドキュメントか。読み手がいなければ書く必要はない |
| 3 | When | いつ必要になるドキュメントか。あるいはいつ更新すべきか |
| 4 | How | 本文。どのようにするのか。動作環境や手順、図など |
| 5 | Why | なぜHowのような内容になったのか |
補足として、1については情報が必要な人が、必要であると分かる文章にします。2についてはチームの構成によって変わってきます。たとえばプロフェッショナルだけで構成されるチームには初歩的なドキュメントは必要ないでしょう。
また、基本的に客観的な情報のみを書き、書き手の主観を入れるときはそれが分かるように注意書きをすべきだと思います。ドキュメントの内容を検討するときに議論しやすくするためです。
いつドキュメントを書くか
ドキュメントを書くタイミングは早すぎず遅すぎず、それが必要になったときに書いてある状態にしておくのが望ましいです。
アジャイル開発は頻繁に変更があるので、ドキュメントにも頻繁な変更が入ります。最初から完全なドキュメントをつくってしまうと時間がかかるし、修正コストも大きくなります。小さくはじめて育てていく意識があるといいと思います。
どこでドキュメントを書くか
ドキュメントを書く場所に必要な要素としては、アクセスしやすく、更新しやすいことが大切だと思います。たとえばesaは「情報を育てる」ためのドキュメント共有サービスなので、書く場所として適していると思います。
まとめ
ドキュメントは、書くタイミングや内容の要点を抑えた上で書くことで、ソフトウェアの価値を高めることにつなげられます。ドキュメントを書くときは4W1Hを意識して、必要最小限の内容にするとよいと思います。
