私はテクニカルライターとして、開発ドキュメントを書いています。また元エンジニアで、エンジニアとしても開発ドキュメントを書いたり、レビューをしていました。
この記事では、開発ドキュメントのレビューをする方法や、レビューを依頼するときに私が気をつけていることをまとめています。エンジニアやテクニカルライターの方にとって、開発ドキュメントをレビューするときの参考になればと思います。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
開発ドキュメントにおけるレビューとは
開発ドキュメントに限らないことですが、文章におけるレビューとは、「文章の作成者とは別の人=レビュアーが、文章や情報の誤りについて指摘することで、よりよい文章にするためのプロセス」のことをいいます。
やることは、次の3つになります。
| 優先度 | プロセス | 内容 |
|---|---|---|
| 1 | 校閲 | 情報の誤りを直す |
| 2 | 校正 | 文字の誤りを直す |
| 3 | 推敲 | 文章を練り直す |
レビューでやることについて、優先度をもとに見てみます。
レビューにおける優先度
レビューにおける優先度は「校閲 > 校正 > 推敲」の順番になります。まず、文章の情報に誤りがある場合は、そもそも文章を公開すべきではありません。第一に、情報の正しさを確認する必要があります。
次に文字の正しさを確認します。誤字・脱字などがないか、です。校正は目視でも行いますが、どうしても確認漏れが出てきてしまいます。
これを防ぐために、自動校正を取り入れると、確実かつ効率的に校正を行うことができます。自動校正については、「開発ドキュメントの文章を自動で校正する方法【textlint】」をご覧ください。
最後に推敲です。推敲は、文章をより読みやすく、わかりやすくするためのプロセスになります。例えば文章の構成を変えたり、内容を追加したりします。推敲については、「開発ドキュメントの文章を推敲する方法」をご覧ください。
文章をよくする以外の目的
レビューの主な目的については、説明した通りです。ただ、レビューには、文章をよりよくする以外にも重要な役割があります。それは次の2つになります。
- 変更に対する影響範囲の確認
- メンバーの教育
変更に対する影響範囲の確認
まずひとつ目に、レビューでは開発ドキュメントに対する変更の範囲が適切かどうかを確認します。変更によって、開発ドキュメントの既存のページを修正する必要はないか。このようなことを考える必要もあります。
文章以外にも、変更によって関係者との調整が必要ではないか。例えば新しく登場した用語について、開発ドキュメント上で使用してもよいかどうかを広報に確認したり、利用規約等については法務に確認したり、といったことが必要になります。
こういったことは、もちろん開発ドキュメントの変更に対する要件ができた段階でも確認しますが、レビューのプロセスでも確認しておくとよいです。
メンバーの教育
レビューのもうひとつの目的は、メンバーの教育です。レビューはよりよい文章にするプロセスです。このため、レビューをしたり、レビューを受けること自体が、テクニカルライティングに関する学びの場となります。
これが、よりよい文章を書けるきっかけになります。また、レビューの内容をチーム内で共有すれば、チーム共通の財産にもなります。
レビュー時の観点
ここでは、開発ドキュメントのレビューにおいて、どこを見るのか、どうコメントするかのふたつを見ていきます。まずはレビュー時の観点についてです。
開発ドキュメントをレビューするときは、前述した通り、校閲・校正・推敲、これに加えて影響範囲について確認していきます。
校閲
校閲では、情報の誤りを見つけて直します。特に、次のような情報が出てきたら、その根拠となる資料等を確認します。
- 固有名詞：メソッド名など
- 数字：日付や値など
またソースコードがある場合は、動作環境をもとに検証します。校閲については、情報に詳しいプロダクトマネージャーや開発者がいれば、その方にレビューを依頼するのも重要です。
校正
校正では、文字の誤りを見つけて直します。例えば、次のようなものがないか確認します。
- 誤字・脱字
- 表記のばらつき：ウェブとWebなど
- 閉じひらきの誤り
- ですます調・である調の混用
校正については、目視で行うこともできますが、自動校正を活用すると効率よく校正を行うことができます。自動校正については、「開発ドキュメントの文章を自動で校正する方法【textlint】」をご覧ください。
推敲
推敲では、文章を練り直します。つまり、より読みやすい、わかりやすい文章にするためのコメントをします。
具体的には、次のような項目を確認します。
- 一文を短く切る
- 結論を先に述べる
- 指示語を使わない
- 主語を明確にする、述語との距離を近づける
- ひらく・閉じるを統一する
- 再現条件を示す
- 前提を揃える
- 見出しや箇条書き、表などを適切に用いる
- 読者に伝わる用語を使う
この項目は、「開発ドキュメントの書き方。意識したい9つのこと【技術編】」より引用しています。あわせてご覧ください。
影響範囲
文章に直接関係することではないですが、レビューにおいては影響範囲を確認することも重要です。
開発ドキュメントの変更に関連して、別のページを修正する必要はないか。あるいは、法務面の確認や、セキュリティチェックを実施する必要がないか、なども確認します。
特に後者は、ややテクニカルライティングの業務とは離れている気もしますが、こういったところもケアできることが重要だと思っています。
コメントの書き方
レビュー中に、修正点や改善した方がよいところを見つけたら、コメントをします。このとき、次のふたつのことに気をつけます。
- 作成者が対応しやすいようにする
- 感情面に配慮する
作成者が対応しやすいようにする
作成者が、レビューをもらったときに対応しやすいようにするには、コメントに重要度を添えます。
レビュー中のよくある問題として、コメントをもらったのはいいものの、「どう対応すればいいかわからない」ということがあります。こういった問題を防ぐために、コメントに重要度を添えます。
重要度には、代表的なものとして次の3つがあります。
| 重要度 | 内容 |
|---|---|
| Must | 必ず対応すべき |
| Nice to have | 可能であれば対応した方がよい |
| Nits | 対応しなくても問題ない |
このとき、できるだけMustかNice to haveのものをコメントするように心がけます。なぜなら、Nits=Nitpicking（細かい指摘）は対応した方がよいかが分かりづらいためです。
また、コメントをするときは、重要度の根拠を示すことも大切です。「なぜMustなのか」ということが分かると、作成者もそのコメントの内容に対応しやすくなります。
他のよくある例として、IMO = In my opinion（私の意見としては）というものもあります。ただこれはNitsよりもさらに対応すべきかどうかが分からないので、避けた方が無難だと思います。
個人的には、対応してもしなくてもどちらでもよいことはあまりコメントしないようにしています。その方がレビューがスムーズに進みますし、作成者の気持ちにも配慮できるためです。
感情面に配慮する
レビューにおけるコメントは、場合によってはネガティブに受け取られる可能性があります。これは仕方のないことですが、次のことに気をつけることで、ポジティブなレビューに近づけることができます。
- 表現を柔らかくする
- 絵文字を用いる
- 客観的な根拠を示す
- よいところもコメントする
- 口頭での確認も活用する
これに限らず、大切なのは「相手を気づかう」ということだと思います。普段のコミニケーションと同じように相手に配慮することで、よりよいレビューになると思います。
また、口頭でレビューの内容を確認することも重要ですが、その際は口頭で話した内容をコメントとしてメモします。こうすることで記録として残りますし、他のメンバーが会話の内容を参照することもできます。
レビューを依頼する方法
レビューは、依頼するときにも気をつけることがあります。これは、レビュアーに効率よくレビューをしてもらうために必要になります。
まず、レビューをお願いする前に、しっかりと推敲をする必要があります。これについては、「開発ドキュメントの文章を推敲する方法」をご覧ください。その上で、開発ドキュメントの要件を整理して提示します。具体的には、レビューを依頼するときに次のことを書きます。
- 変更の概要
- 関連情報：Wikiなど
- 公開予定日
- 関係者：企画、開発担当者など
- スコープ：今回の対応範囲
開発ドキュメントの要件については、「開発ドキュメントの要件を整理する方法」をご覧ください。あとは、特に見てほしいポイントや、困っていることがあれば書いておくとよいです。
おわりに
レビューは、開発ドキュメントをよりよいものにするために必要なプロセスになります。レビューをする側も、依頼する側も気をつけることで、効率的かつ効果的なレビューを行うことができます。
