開発ドキュメントの要件を整理する方法

私はテクニカルライターとして働いていて、複数のチームと連携をしながら開発ドキュメントを書いています。

今はある程度スムーズに開発ドキュメントを書けていますが、以前は公開までの作業をうまく進められないことがありました。

例えば、開発ドキュメントを書くために必要な情報がわからなかったり、公開直前のレビューで差し戻されたり、レビュワーの方にとって優先度が低く、なかなかレビューが進まなかったり。

こういった問題のほとんどは、文章を書く前に、要件をしっかりと整理することで解決します。

この記事では、周囲の状況に左右されず、効率的に開発ドキュメントを公開までもっていくための方法についてまとめています。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。趣味はスプラトゥーンです。

目次

開発ドキュメントの作成フロー

まず、そもそも「どうやって開発ドキュメントを作るのか」について整理しておきます。詳細については別の記事に書く予定ですが、概要は次のような感じになると思います。

手順項目概要
1チケット化開発ドキュメントに対する要求が生まれる
2要件整理チケット作成者からの要件を整理する
3企画読者からの要求を整理する
4アウトライン作成文章の骨組みを作る
5執筆文章を作成する
6推敲文章を練り直す
7レビュー関係者からのレビューを受ける
8公開文章を公開する

書くことが決まった後にやるのが、この記事で説明する要件整理になります。

要件整理とは何か

要件整理とは、チケット作成者からの要件を整理することをいいます。具体的には、チケットの対応範囲やスケジュール、関係者などを一枚のページにまとめます。

「こういう文章を書いてほしい」という要求があった時点では、まだその要件は曖昧なことが多く、その状態で文章を書きはじめてしまうと、作業が行き当たりばったりになってしまう可能性があります。

この曖昧な状態から、実際に開発ドキュメントのを書く上で必要な情報を整理していくのが要件整理です。

詳細は後述しますが、具体的には次のようなことを決めていきます。

手順項目概要
1概要チケットの概要
2関連情報チケットや関連ページへのリンクなど
3スケジュール公開までのスケジュール
4関係者チケット作成者や企画、開発担当者など
5スコープチケットの対応範囲
6メモ文章を書くのに必要な、網羅的な情報
7議事録チケットに関するミーティングの議事録
8疑問点チケットを進める上で生まれた疑問

要件整理は、自分が見るのはもちろんですが、他の関係者も見る重要な資料になります。例えば、レビュワーはこの要件整理を見ることで、スムーズにレビュー作業に入ることができるようになります。

要件整理の必要性

要件整理をする目的は、開発ドキュメントを公開するまでの不確実性をなくして、効率的に作業を進められるようにすることです。

開発ドキュメントを書くときは、いろんな問題があると思います。例えば、

  1. 何を書けばいいのかわからない
  2. 書いた後で差し戻されてしまう
  3. 公開前になって、間に合いそうにないことに気づく

などがあります。

1については作業の対応範囲が不明瞭だったり、2はレビュアーが誰かわからなかったり、3はスケジュール管理上の問題だったりします。

他にも、レビュー時にレビュアーがチケットの内容を把握するのに時間がかかることも問題になりがちです。

しっかりと要件を整理しておけば、こういったたいていの問題は防ぐことができます。

要件を整理する方法

要件整理は、「このページを元にすれば問題なく文章が書ける」という網羅性が重要になります。開発ドキュメントを書く上で、必要な情報をまとめていきます。

要件整理は、自分だけでなくレビュアーなど他の人も見る可能性がある文書になります。このため、社内Wikiなどに書くとよいでしょう。

参考までに、ドキュメント管理ツールであるNotionで要件を整理した例を次に示します。

Notionで要件整理をした例 Notionで要件整理をした例

1. 概要

チケットの概要を1〜3行程度で簡潔にまとめたものです。チケットがどういうものかを把握するのに役立ちます。

自分だけでなく、レビュアーが読むこともふまえて記述します。

2. 関連情報

開発ドキュメントを書くにあたって役に立つ関連情報を表にまとめます。例えば、

  • チケットへのリンク
  • 仕様や議事録などのページへのリンク
  • コミュニケーションツールへのリンク(Slackのちゃんねるなど)
  • 公開日
  • 対応する言語

などを書きます。

3. スケジュール

開発ドキュメントを公開するまでの具体的なスケジュールを決めます。チケットが作られたタイミングでは、決まるとしても公開日くらいだと思います。

これをもっと細分化して、例えばいつまでにドラフトを書くか、レビューを依頼するかなどの日を決めます。こうすることで、関係者への期待値を調整することができます。

進捗を共有したい重要なミーティングがあれば、その日付を書いておくのもよいです。

4. 関係者

チケットを進める上で関係する人を表にまとめます。ここでまとめた人を対象に、進捗を共有したり、レビューを依頼したりします。

例えば、次のような役割の方を書いていきます。ここは製品によって変わってくると思います。

  • チケット作成者
  • 企画担当者
  • 開発担当者
  • レビュワー
  • QA担当者

5. スコープ

このチケットで何をするのか、あるいは何をしないのかを決めます。また、項目ごとに優先度を決めます。

こうすることで、文章を書いた後に「これを書いてほしかった」「これは書かないでほしかった」といった期待値に関する問題を防ぐことができます。

優先度については、次のようなラベルをつけるとわかりやすいです。

ラベル概要
Must必ず対応すること
Nice to have可能であれば対応すること
Out of specこのチケットでは対応しないこと

6. メモ

文章を書く上で必要な情報を網羅的にまとめていきます。例えばチケットが生まれた背景や、具体的な仕様、その他の補足情報などを書いていきます。

ここも自分だけでなくレビュアーが見ることを意識して、わかりやすいように書きます。

7. 議事録

チケットに関するミーティングを行うことがあると思います。そのときの議事録を書いておきます。開発ドキュメントを書くときの資料になったりします。

8. 疑問点

チケットが生まれた段階では、疑問点がたくさんあると思います。例えば、

  • どのページに書けばいいのか
  • レビュアーは誰なのか
  • いつ公開すればいいのか

などです。こういった要件についての疑問を洗い出します。ここで洗い出しつつ、ミーティングの場などで質問して、解決をめざします。

この疑問点を洗いだせるか、早い段階で解決できるかが、スムーズに作業を進める上で重要になってきます。

おわりに

他にも、目次や更新履歴などを書いておくと、ページとしての使いやすさが高まります。

開発ドキュメントを書く上では、まず要件を整理しておくと、公開までの障壁がなくなり、スムーズに公開まで進められるようになります。

開発ドキュメントの作成をうまく進められなくて悩んでいましたら、ぜひ参考にしてみてください。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。趣味はスプラトゥーンです。

関連記事関連書籍
applis
アプリケーション開発について学ぶブログ
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは下記よりお願いいたします
お問い合わせ
© 2020-2022 applis