開発ドキュメントを書くことになったとき、何を書けばよいかが分からない、ということはないでしょうか。この問題は、開発ドキュメントを書くために必要な情報が揃っていない場合に起こりがちです。
私はテクニカルライターとして、開発ドキュメントを書いています。「どうすれば効率的に開発ドキュメントを書いていけるか」を考える中で、最初に必要な情報を集めること、つまり変更要求の方法が重要だと感じました。
この記事を読むことで、開発ドキュメントを書く上で必要な情報が集まり、効率的に書けるようになればと思います。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
変更要求とは何か
この記事でいう変更要求とは、「開発ドキュメントに対して変更したい内容を記入したもの」をいいます。
開発ドキュメントを書くことになったとき、そこには何かしらの変更要求があります。例えば、次のような変更要求が最初に発生することになります。
- メンバーのために開発環境を構築する手順をまとめたい
- APIに機能を追加したので、開発ドキュメントに追記してほしい
- 既存の開発ドキュメントに誤りがあるので修正したい
変更要求を上げる人（=要求者）は、あなたや他のメンバー、あるいは外部に公開している開発ドキュメントの場合は、その製品の利用者かもしれません。
このように、開発ドキュメントに対して変更したい内容を記入したものが変更要求です。なお、この変更要求は、GitHubのIssueのようなチケットで管理されたりします。
なぜ変更要求のときに情報を集めるのか
変更要求のときは、要求者から「変更したい内容に関する情報」をもらうことが重要です。なぜなら、情報がないと要件の整理が非効率になるからです。
例えば、「開発ドキュメントにこういう誤りがあるので修正してほしい」という依頼を受けたとします。このとき、次のような情報が分からないときがあります。
- どのページのどの部分なのか
- いつまでに修正するべきか
- 修正内容は誰にレビューしてもらえばいいか
この場合、要件を整理するのに必要以上に時間がかかってしまいます。また、情報が曖昧なまま開発ドキュメントを修正してしまうと、そもそもの意図を履き違えた変更になってしまうかもしれません。
こういった問題を防ぐためにも、あらかじめ変更に関する情報を集めることが重要になります。
変更要求のときに集める情報
開発ドキュメントに新しいページを追加したり、既存の部分を変更するとき、あらかじめ要求者から次の情報を集めておきます。
| 順番 | 項目 | 概要 |
|---|---|---|
| 1 | 概要 | 変更の概要が分かるよう簡潔にまとめる |
| 2 | 関連する資料 | 変更に関連するWikiや外部ページのURLなど |
| 3 | 関係者 | レビュアーや、疑問に対する質問相手など |
| 4 | スケジュール | いつ公開したいか、あるいはいつまでに公開しておきたいか |
| 5 | 変更の詳細 | 変更するページ、重要度、またどう変更するか |
| 6 | 備考 | 変更に関して、その他に伝えておきたいこと |
例えば、あなたが「こういう開発ドキュメントを書いてほしい」という依頼をされたら、まず関連する資料やレビュアー、スケジュールといった情報を要求者から集めます。
これらの情報があれば、「この変更要求に対応する・しない」の判断がしやすくなります。また、実際に対応するときに必要な情報があるので、すぐに次の作業に着手できます。
変更の詳細における重要度
この中の「変更の詳細」について、重要度は次のように設定するとよいです。これにより、リソース状況に応じて対応するかどうかの判断がしやすくなります。
| 順番 | 重要度 | 概要 |
|---|---|---|
| 1 | Must | 必ず対応してほしい |
| 2 | Nice to have | できれば対応してほしい |
変更要求の手順をまとめたページを公開する
変更要求のときに集める情報が分かったとして、では実際にどう変更要求を記入してもらえばよいのでしょうか。これは、変更要求の手順をまとめたページを作成して、公開しておくとよいです。
要求者は、このページの内容にしたがって変更要求を出すことになります。
このページの目的は、要求者に「変更要求のときに集める情報」で示した情報を記入してもらうようことです。こうすることで、質の高い変更要求が来るようになり、要件の整理が効率的に行え、結果としてよりよい開発ドキュメントにつながります。
また、例えば変更要求をチケットで管理している場合、変更要求用のテンプレートを作っておくのも効果的です。これはGitHubのIssueテンプレートがイメージしやすいかもしれません。
まずは変更要求の手順をまとめたページを作成してみましょう。
ページ作成時に気をつけること
変更要求のときに集める情報をいくつか紹介しましたが、これらの項目はすべての要求者に対して記入を必須にするべきではありません。
要求者によっては、分からない項目があったりします。この場合は「無理に記入しなくてもよい」ということを伝えておく必要があります。なぜなら、変更要求を書いてもらう目的は、できるだけ要件整理を効率的に行うことだからです。つまり、分からないことを求めても意味がありません。
変更要求を出すのが難しいと、逆に変更要求が来なくなる危険性もあります。例えば一般の利用者によるバグの報告について考えてみます。バグの報告については、バグの内容や再現条件が分かればよく、レビュアーやスケジュールについては関与できないと思います。
こういった「書くことが難しい項目」まで要求してしまうと、貴重なバグ報告がなくなるかもしれません。
要求方法をまとめたページを作るときは、すべての人にすべての項目を必須にしないようにする必要があります。
まとめ
変更要求とは、開発ドキュメントに対して変更したい内容を記入したものです。あらかじめ必要な情報を集めておくことによって、効率的に開発ドキュメントが書けるようになります。
注意点として、変更要求を出す人によっては記入しなくてもよいようにするなど、変更要求の手順を調整する必要があります。
