ドキュメントレビューの苦しさを解決する「レビューのレビュー会」/ "Reviewing Reviews" solves the pain of document review

ドキュメントを書いて、他の人にレビューしてもらう。そのレビューの工程を「苦しいな」と感じたことはありませんか？私はあります！指摘された箇所の修正について折り合いが付かない。あるいは特定のプルリクエストで話し合った問題が、他のメンバーに共有されずに別のプルリクエストで繰り返される。レビューを受ければ受けるほどプルリクエストが肥大化していって、いつまでもリリースできない。そんな苦しさからさっと抜け出すため、我々のチームで2021年からはじめた「レビューのレビュー会」についてお話しします。

堀越 良子 / @mochikoAsTech / LINE株式会社 テクニカルライター。元インフラエンジニア。ねこが好き。

※この資料は以下のイベントで発表されたものです
https://line.connpass.com/event/276934/

Transcript

1. LINE Technical Writing Meetup vol. 22 ドキュメントレビューの苦しさを解決する 「レビューのレビュー会」 LINE Corporation Developer Content Team Yoshiko Horikoshi 9th March 2023 19:00-21:00
2. 1: ドキュメントレビューの苦しさを解決する 「レビューのレビュー会」 2: テクニカルライターが GPT-3 を使ってみた話 3: Questions and Answers 9th March 2023 19:00-21:00 LINE Technical Writing Meetup vol. 22
3. 発表資料はSpeaker Deckでも公開しますので 発表内容や画⾯キャプチャ、動画のURLなどは ⾃由にツイートしてください
4. ⾃⼰紹介
5. はじめまして 「ほりこし」です
6. LINE Corporation Developer Content Team
7. 2020年1⽉から LINEでテクニカルライター
8. Yoshiko Horikoshi @mochikoAsTech プログラマ（3年） 広報（4年） インフラエンジニア（7年） 2020年1⽉からLINEでテクニカルライター
9. https://techbookfest.org/organization/12790004
11. 「テクニカルライターってなに︖」と思ったら LINEの開発者向けドキュメントを⽀える 「テクニカルライティング」の専⾨チーム というセッションの動画と記事をどうぞ https://www.youtube.com/watch?v=HjKvDK50iY0 https://logmi.jp/tech/articles/325624
12. 今⽇話す内容
13. ドキュメントレビューの 苦しさを解決する 「レビューのレビュー会」
14. ドキュメントレビューの 苦しさを解決する 「レビューのレビュー会」
15. ドキュメントレビューの 苦しさを解決する 「レビューのレビュー会」
16. 質問です
17. ドキュメントを書いて 他の⼈にレビューしてもらう… そのレビューの⼯程を「苦しいな」と 感じたことはありませんか︖
18. 私はあります︕
19. たとえばこんな 苦しさがある
20. 苦しい例 その1 指摘されたコメントを読んでも 何をどう直せと⾔われているのか 分からない
21. LINE Technical Writing Meetup vol. 6 ⽂章への指摘を上⼿に受け⽌めて活かす⽅法 YouTube: https://youtu.be/H-1JBMLny_w?t=879 Slide: https://speakerdeck.com/line_developers/how-to-improve-your-writing-by-listening-to-suggestions
22. 「具体的にどう直すべきか」が読み取れない指摘の例︓ • 仕様理解が⾜りていないようです • ここ、もうちょっと分かりやすくなりませんか︖ • ◦◦の説明に怪しいところがあります • この説明だと誤解させるので直してほしいです 「LINE TWM vol. 6 ⽂章への指摘を上⼿に受け⽌めて活かす⽅法」から再掲
23. ⼿を動かして直す前に どこをどう直してほしいのか お気持ち推測タイムが必要
24. そしてお気持ち推測が 間違っていると 折⾓直してもまたやり直し
25. 苦しい例 その1 指摘されたコメントを読んでも 何をどう直せと⾔われているのか 分からない
26. LINE Technical Writing Meetup vol. 6 ⽂章への指摘を上⼿に受け⽌めて活かす⽅法 YouTube: https://youtu.be/H-1JBMLny_w?t=879 Slide: https://speakerdeck.com/line_developers/how-to-improve-your-writing-by-listening-to-suggestions
27. 苦しい例 その1 指摘されたコメントを読んでも 何をどう直せと⾔われているのか 分からない →この苦しさは発⽣していない
28. 苦しい例 その2 指摘された箇所の修正について レビューアーとレビューイーの 間で折り合いが付かない
29. 苦しい例 その2 指摘された箇所の修正について レビューアーとレビューイーの 間で折り合いが付かない →この苦しさは起きていた
30. 苦しい例 その3 レビューを受ければ受けるほど プルリクエストが肥⼤化して いつまでもリリースできない
31. 苦しい例 その3 レビューを受ければ受けるほど プルリクエストが肥⼤化して いつまでもリリースできない →この苦しさも起きていた
32. 苦しい例 その4 特定のプルリクエストで ⾒落としてhotfixした問題が 他のメンバーに共有されずに 別のプルリクエストで繰り返される
33. 苦しい例 その4 特定のプルリクエストで ⾒落としてhotfixした問題が 他のメンバーに共有されずに 別のプルリクエストで繰り返される →この苦しさもあった︕
34. 苦しい︕つらい︕
35. リリース前の レビューの⼯程に すごく時間がかかると 段々苦しくなってくる
36. そんな苦しさから抜け出すため 我々のチームでは2021年から 「レビューのレビュー会」 というものをはじめました
37. きっかけは レビュー観点共有会を 開催してくれたこと
38. ミスが起こったときに 「こういう観点でレビューすべきだった」 をふりかえる機会とか、 hotfixで対応した内容を チームで共有する機会がほしい
39. レビュー観点をレビューする会 通称「レビューのレビュー会」を ⽉1回やることになった
40. 「レビューのレビュー会」 の開催⽅法は︖
41. カレンダーに⽉1の繰り返し予定を⼊れる 参加メンバーはチームのライター全員
42. 「レビューのレビュー会」でやること 1. Discussion itemsについて話し合う 2. Hotfixを確認する 3. Next actionsを決める
43. レビュー指摘の中で ⽅針が決まっていないものがあったら レビューのレビュー会⽤の Discussion itemsに書いておく
44. 1ヶ⽉の間に結構な数の 「⽅針が決まっていなかったこと」 が溜まるので レビューのレビュー会で 全員で⽅針を決めていく
45. 直近1ヶ⽉の間に発⽣した Hotfixも確認して 「こういう観点でレビューしないと こういう⾒落としがあるんだね」 も全員で共有する
46. ⽅針が決まったら 「チームのライティングルールに追記する」 「⽅針に従って⼀⻫修正するチケットを作る」 みたいなNext actionを書いて終わる
47. 「レビューのレビュー会」誕⽣以前︓ レビュー指摘の中で ⽅針が決まっていないものがあったら →決まるまで進めない
48. 「レビューのレビュー会」誕⽣後︓ レビュー指摘の中で ⽅針が決まっていないものがあった →Discussion itemsに積んでおいて さっとリリースに進める
49. Discussion itemsに積むことで 次のレビューのレビュー会までは いったん忘れてていいや︕ と安⼼して棚上げできるようになった
50. レビューのレビュー会の Discussion itemsから ⼀部をご紹介
51. • 画像ファイルの命名規則 • Prettierをかけるタイミングはいつか • 全⾓数字が残っていたので撲滅するか • 英語で箇条書きの末尾にピリオドを書くか • 実際のUIテキストやボタン、タブなどを表す表現について • 英語で⽂中の「unicode」は先頭⼤⽂字︖⼩⽂字︖ • 「Japanese only」という表現は避けるべきか • レスポンスのJSONで含まれないこともあるプロパティをなんと呼ぶ︖ • PCで使えるLINEの呼称について • ニュースにつける「⾮推奨」と「サポート終了」のタグについて • 400番台のエラーを返す時の書き⽅
52. • 環境ごとの⼿順はどこまでサポートするか • 「公開」と「開⽰」の使い分け • AIファイルの管理ルールについて • アドモニションにするしない問題 • 「紐付け」or「紐づけ」 • 障害対応の進め⽅ • ⽂字数は「多い/少ない」か「⼤きい/⼩さい」か • LINE Seedが作図のフォントに使えそう • 多⾔語化 vs 国際化 • FAQのQの末尾は「︖」で締めるべきか • ⽇時の統⼀ルール
53. 最初の頃はDiscussion itemsが 毎回7、8個はあったけど 段々整備されてきて 最近は1、2個だったり 何もなくてスキップになることもある
54. 「レビューのレビュー会」で レビューの⼯程にあった 「苦しさ」が解決できた
55. 1: ドキュメントレビューの苦しさを解決する 「レビューのレビュー会」 2: テクニカルライターが GPT-3 を使ってみた話 3: Questions and Answers 9th March 2023 19:00-21:00 LINE Technical Writing Meetup vol. 22
56. 1: ドキュメントレビューの苦しさを解決する 「レビューのレビュー会」 2: テクニカルライターが GPT-3 を使ってみた話 3: Questions and Answers 9th March 2023 19:00-21:00 LINE Technical Writing Meetup vol. 22