ドキュメントレビューのガイドライン【CCGレビュアー向け】
このブログについて
本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) 1 のレビュアー向けに公開しているブログです。 一般的なドキュメントレビューでも参考になる部分があると思うので、ブログにて公開しています。
ドキュメントの追記・修正は GitHub プルリクエスト上でやりとりされます。 プルリクエストのレビューの方法や意識について記載します。
はじめにまとめ
本ページの要旨は以下のとおりです。
- レビューの目的
- 正しく、より良いコンテンツを提供する
- レビューの観点
- 改善につながること
- 正しい内容であること (校閲)
- 表記ゆれや誤字脱字が無いこと (校正)
- より良い文章にできないか (推敲)
- レビューの意識
- 顧客視点
- 執筆者への感謝
- 執筆者の負荷軽減
- Suggestion を活用しよう
- レビュー手順
- 承認する場合は「Approve」
- 指摘がある場合は「Request changes」
- 相談したい場合は「Comment」、もしくは同期的に話す
- 一定数のApproveが得られたらマージ
- 便利設定
- Slack通知
レビューの目的
読み手(顧客) を意識します。
正しく、より良いコンテンツを読み手に提供するために、レビューを行います。
レビューの観点
レビューで着目する観点をガイドライン化します。
CCGの改善に繋がるか
プルリクエストは、CCGの改善に繋がる内容であるべきです。 CCGの方向性や各種コンテンツの目的に沿ったものかをチェックしましょう。
CCGの方向性については、 以下ブログもしくは社内で管理している「CCGの思想」を参照してください。
組織管理ガイドや Security Hubガイドなどの各コンテンツ単位でも、 それぞれ目的を明文化しています。 それらも確認ください。
正しい内容であるか
いわゆる 校閲 です。 情報が正しいかどうかチェックします。
例えばAWSサービスで間違えた仕様を書いていたり、 ベストプラクティスではない内容を書いていないか確認します。
(執筆者向けですが、出典元や参考にしたリンクは記載しておくのが良いでしょう)
表記ゆれや誤字脱字が無いか
いわゆる 校正 です。 表記ゆれや誤字脱字が無いかチェックします。
なお、校正を補助するツールとして textlint を活用しています。 冗長表現やAWSサービスのスペルミスは、ある程度は自動検出されるようになっています。
より良い文章にできないか
いわゆる 推敲 です。 より分かりやすく、良い文章にできないかチェックします。
ただし、校閲や校正ほど優先度は高くありません。
レビューの意識
読み手(顧客)視点でレビューする
これは執筆者にも、レビュアーにも言えることです。
読み手(顧客)のスキルや、活用するシチュエーションを想像・意識しましょう。
執筆者への感謝
どんな内容であれ、 コンテンツ改善に向けて前進してくれた 執筆者に感謝します。 その前提でレビューします。
あと指摘は攻撃的に受けとめられがちです。 「ここが良くない」指摘ではなく、 「こうしたらより良くなる」指摘を意識すると良いでしょう。
執筆者の負荷軽減
なるべく具体的な指摘を心がけます。 (抽象的な指摘や議論は、同期的なコミュニケーションで進めたほうが良いケースが多いです)
GitHub の Suggestion機能を活用しましょう。 これはレビュー時に「こんな記載はどう？」といった提案ができる機能です。 例えば単純な誤字脱字であれば、 Suggestion を使って指摘しましょう。 執筆者の負担軽減に繋がります。
具体的なレビュー手順
レビュー手順の全体像
以下の図は、執筆者とレビュアーとのコミュニケーションの簡易フローです。
レビュアーは『自分が担当になっている Pull Request』 を見つけるところから始まります。 これは [Reviews → Awaiting review from you] から確認できます。
レビューには 3種類、 Approve , Request changes , Comment が あります。 それぞれ用途に合わせて活用します(後述)。
基本的には Approve もしくは Request changes を使う
基本的には Approve (承認) もしくは Request changes (指摘あり) を使ってください。
Request changes で指摘を行うと、 [Reviews → Changes requested] で指摘一覧をフィルターできます。
抽象的な or 相談したいトピック がある場合は Comment
相談したいトピックがある場合は適宜 Comment を使ってください。 ただし、Comment 自体はレビューステータスは変わらないので、 非同期的なフローには不向きであることを抑えておきましょう。
また、場合によっては同期的に相談したいことを話し合ったほうが早いこともあります。
マージ可能になったら
開発環境である develop ブランチへのマージは 2人以上 の Approve が必要です。 これは GitHub のブランチ保護ルールで設定しています。
Request changes が無い状態で、2人以上の Approve が得られたプルリクエストは、 レビュアーがマージしてOKです。
任意の便利設定
Slack通知
GitHub周りのイベントをSlackへ通知できます。 プルリクエストのレビュー依頼が来ていることを逃したくない場合は設定ください。
もしくは Slackチャンネル #notify-ccg-github にて Issue や Pull Request のイベントを垂れ流しています。 必要に応じて参加ください。
おわりに
以上、Classmethod Cloud Guideline のレビュアー向けガイドラインでした。
良いコンテンツにするべく、どんどんレビューしていきましょう！
