私はテクニカルライターとして働いていて、複数のチームと連携をしながら開発ドキュメントを書いています。今はある程度スムーズに開発ドキュメントを書けていますが、以前は公開までの作業をうまく進められないことがありました。
例えば、開発ドキュメントを書くために必要な情報がわからなかったり、公開直前のレビューで差し戻されたり、レビュワーの方にとって優先度が低く、なかなかレビューが進まなかったり。こういった問題のほとんどは、文章を書く前に、要件をしっかりと整理することで解決します。
この記事では、周囲の状況に左右されず、効率的に開発ドキュメントを公開までもっていくための方法についてまとめています。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
開発ドキュメントの作成フロー
まず、そもそも「どうやって開発ドキュメントを作るのか」について整理しておきます。詳細については「開発ドキュメントを公開するまでの基本的な手順」をご覧ください。
| 手順 | 項目 | 概要 |
|---|---|---|
| 1 | チケット化 | 開発ドキュメントに対する要求が生まれる |
| 2 | 要件整理 | チケット作成者からの要件を整理する |
| 3 | 企画 | 読者からの要求を整理する |
| 4 | アウトライン作成 | 文章の骨組みを作る |
| 5 | 執筆 | 文章を作成する |
| 6 | 推敲 | 文章を練り直す |
| 7 | レビュー | 関係者からのレビューを受ける |
| 8 | 公開 | 文章を公開する |
書くことが決まった後にやるのが、この記事で説明する要件整理になります。
要件整理とは何か
要件整理とは、チケット作成者からの要件を整理することをいいます。具体的には、チケットの対応範囲やスケジュール、関係者などを一枚のページにまとめます。
「こういう文章を書いてほしい」という要求があった時点では、まだその要件は曖昧なことが多く、その状態で文章を書きはじめてしまうと、作業が行き当たりばったりになってしまう可能性があります。
この曖昧な状態から、実際に開発ドキュメントのを書く上で必要な情報を整理していくのが要件整理です。詳細は後述しますが、具体的には次のようなことを決めていきます。
| 手順 | 項目 | 概要 |
|---|---|---|
| 1 | 概要 | チケットの概要 |
| 2 | 関連情報 | チケットや関連ページへのリンクなど |
| 3 | スケジュール | 公開までのスケジュール |
| 4 | 関係者 | チケット作成者や企画、開発担当者など |
| 5 | スコープ | チケットの対応範囲 |
| 6 | メモ | 文章を書くのに必要な、網羅的な情報 |
| 7 | 議事録 | チケットに関するミーティングの議事録 |
| 8 | 疑問点 | チケットを進める上で生まれた疑問 |
要件整理は、自分が見るのはもちろんですが、他の関係者も見る重要な資料になります。例えば、レビュワーはこの要件整理を見ることで、スムーズにレビュー作業に入ることができるようになります。
要件整理の必要性
要件整理をする目的は、開発ドキュメントを公開するまでの不確実性をなくして、効率的に作業を進められるようにすることです。開発ドキュメントを書くときは、いろんな問題があると思います。例えば、次のようなことがあります。
- 何を書けばいいのかわからない
- 書いた後で差し戻されてしまう
- 公開前になって、間に合いそうにないことに気づく
1については作業の対応範囲が不明瞭だったり、2はレビュアーが誰かわからなかったり、3はスケジュール管理上の問題だったりします。他にも、レビュー時にレビュアーがチケットの内容を把握するのに時間がかかることも問題になりがちです。
しっかりと要件を整理しておけば、こういったたいていの問題は防ぐことができます。
要件を整理する方法
要件整理は、「このページを元にすれば問題なく文章が書ける」という網羅性が重要になります。開発ドキュメントを書く上で、必要な情報をまとめていきます。要件整理は、自分だけでなくレビュアーなど他の人も見る可能性がある文書になります。このため、社内Wikiなどに書くとよいでしょう。
参考までに、ドキュメント管理ツールであるNotionで要件を整理した例を次に示します。
1. 概要
チケットの概要を1〜3行程度で簡潔にまとめたものです。チケットがどういうものかを把握するのに役立ちます。 自分だけでなく、レビュアーが読むこともふまえて記述します。
2. 関連情報
開発ドキュメントを書くにあたって役に立つ関連情報を表にまとめます。例えば、次のようなことを書きます。
- チケットへのリンク
- 仕様や議事録などのページへのリンク
- コミュニケーションツールへのリンク（Slackのちゃんねるなど）
- 公開日
- 対応する言語
3. スケジュール
開発ドキュメントを公開するまでの具体的なスケジュールを決めます。チケットが作られたタイミングでは、決まるとしても公開日くらいだと思います。これをもっと細分化して、例えばいつまでにドラフトを書くか、レビューを依頼するかなどの日を決めます。こうすることで、関係者への期待値を調整することができます。
進捗を共有したい重要なミーティングがあれば、その日付を書いておくのもよいです。
4. 関係者
チケットを進める上で関係する人を表にまとめます。ここでまとめた人を対象に、進捗を共有したり、レビューを依頼したりします。例えば、次のような役割の方を書いていきます。ここは製品によって変わってくると思います。
- チケット作成者
- 企画担当者
- 開発担当者
- レビュワー
- QA担当者
5. スコープ
このチケットで何をするのか、あるいは何をしないのかを決めます。また、項目ごとに優先度を決めます。こうすることで、文章を書いた後に「これを書いてほしかった」「これは書かないでほしかった」といった期待値に関する問題を防ぐことができます。
優先度については、次のようなラベルをつけるとわかりやすいです。
| ラベル | 概要 |
|---|---|
| Must | 必ず対応すること |
| Nice to have | 可能であれば対応すること |
| Out of spec | このチケットでは対応しないこと |
6. メモ
文章を書く上で必要な情報を網羅的にまとめていきます。例えばチケットが生まれた背景や、具体的な仕様、その他の補足情報などを書いていきます。ここも自分だけでなくレビュアーが見ることを意識して、わかりやすいように書きます。
7. 議事録
チケットに関するミーティングを行うことがあると思います。そのときの議事録を書いておきます。開発ドキュメントを書くときの資料になったりします。
8. 疑問点
チケットが生まれた段階では、疑問点がたくさんあると思います。例えば、次のようなものです。
- どのページに書けばいいのか
- レビュアーは誰なのか
- いつ公開すればいいのか
こういった要件についての疑問を洗い出します。ここで洗い出しつつ、ミーティングの場などで質問して、解決をめざします。この疑問点を洗いだせるか、早い段階で解決できるかが、スムーズに作業を進める上で重要になってきます。
おわりに
他にも、目次や更新履歴などを書いておくと、ページとしての使いやすさが高まります。開発ドキュメントを書く上では、まず要件を整理しておくと、公開までの障壁がなくなり、スムーズに公開まで進められるようになります。
開発ドキュメントの作成をうまく進められなくて悩んでいましたら、ぜひ参考にしてみてください。
