ドキュメントレビューの苦しさを解決する「レビューのレビュー会」/ "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
   

   View Slide

2. 1:
   ドキュメントレビューの苦しさを解決する
   「レビューのレビュー会」
   2:
   テクニカルライターが
   GPT-3 を使ってみた話
   3: Questions and Answers
   9th March 2023 19:00-21:00
   LINE Technical Writing Meetup vol. 22
   

   View Slide

3. 発表資料はSpeaker Deckでも公開しますので
   発表内容や画⾯キャプチャ、動画のURLなどは
   ⾃由にツイートしてください
   

   View Slide

4. ⾃⼰紹介
   

   View Slide

5. はじめまして
   「ほりこし」です
   

   View Slide

6. LINE Corporation
   Developer Content Team
   

   View Slide

7. 2020年1⽉から
   LINEでテクニカルライター
   

   View Slide

8. Yoshiko Horikoshi
   @mochikoAsTech
   プログラマ（3年）
   広報（4年）
   インフラエンジニア（7年）
   2020年1⽉からLINEでテクニカルライター
   

   View Slide

9. https://techbookfest.org/organization/12790004
   

   View Slide

10. View Slide

11. 「テクニカルライターってなに︖」と思ったら
    LINEの開発者向けドキュメントを⽀える
    「テクニカルライティング」の専⾨チーム
    というセッションの動画と記事をどうぞ
    https://www.youtube.com/watch?v=HjKvDK50iY0 https://logmi.jp/tech/articles/325624
    

    View Slide

12. 今⽇話す内容
    

    View Slide

13. ドキュメントレビューの
    苦しさを解決する
    「レビューのレビュー会」
    

    View Slide

14. ドキュメントレビューの
    苦しさを解決する
    「レビューのレビュー会」
    

    View Slide

15. ドキュメントレビューの
    苦しさを解決する
    「レビューのレビュー会」
    

    View Slide

16. 質問です
    

    View Slide

17. ドキュメントを書いて
    他の⼈にレビューしてもらう…
    そのレビューの⼯程を「苦しいな」と
    感じたことはありませんか︖
    

    View Slide

18. 私はあります︕
    

    View Slide

19. たとえばこんな
    苦しさがある
    

    View Slide

20. 苦しい例 その1
    指摘されたコメントを読んでも
    何をどう直せと⾔われているのか
    分からない
    

    View Slide

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
    

    View Slide

22. 「具体的にどう直すべきか」が読み取れない指摘の例︓
    • 仕様理解が⾜りていないようです
    • ここ、もうちょっと分かりやすくなりませんか︖
    • ○○の説明に怪しいところがあります
    • この説明だと誤解させるので直してほしいです
    「LINE TWM vol. 6 ⽂章への指摘を上⼿に受け⽌めて活かす⽅法」から再掲
    

    View Slide

23. ⼿を動かして直す前に
    どこをどう直してほしいのか
    お気持ち推測タイムが必要
    

    View Slide

24. そしてお気持ち推測が
    間違っていると
    折⾓直してもまたやり直し
    

    View Slide

25. 苦しい例 その1
    指摘されたコメントを読んでも
    何をどう直せと⾔われているのか
    分からない
    

    View Slide

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
    

    View Slide

27. 苦しい例 その1
    指摘されたコメントを読んでも
    何をどう直せと⾔われているのか
    分からない
    →この苦しさは発⽣していない
    

    View Slide

28. 苦しい例 その2
    指摘された箇所の修正について
    レビューアーとレビューイーの
    間で折り合いが付かない
    

    View Slide

29. 苦しい例 その2
    指摘された箇所の修正について
    レビューアーとレビューイーの
    間で折り合いが付かない
    →この苦しさは起きていた
    

    View Slide

30. 苦しい例 その3
    レビューを受ければ受けるほど
    プルリクエストが肥⼤化して
    いつまでもリリースできない
    

    View Slide

31. 苦しい例 その3
    レビューを受ければ受けるほど
    プルリクエストが肥⼤化して
    いつまでもリリースできない
    →この苦しさも起きていた
    

    View Slide

32. 苦しい例 その4
    特定のプルリクエストで
    ⾒落としてhotfixした問題が
    他のメンバーに共有されずに
    別のプルリクエストで繰り返される
    

    View Slide

33. 苦しい例 その4
    特定のプルリクエストで
    ⾒落としてhotfixした問題が
    他のメンバーに共有されずに
    別のプルリクエストで繰り返される
    →この苦しさもあった︕
    

    View Slide

34. 苦しい︕つらい︕
    

    View Slide

35. リリース前の
    レビューの⼯程に
    すごく時間がかかると
    段々苦しくなってくる
    

    View Slide

36. そんな苦しさから抜け出すため
    我々のチームでは2021年から
    「レビューのレビュー会」
    というものをはじめました
    

    View Slide

37. きっかけは
    レビュー観点共有会を
    開催してくれたこと
    

    View Slide

38. ミスが起こったときに
    「こういう観点でレビューすべきだった」
    をふりかえる機会とか、
    hotfixで対応した内容を
    チームで共有する機会がほしい
    

    View Slide

39. レビュー観点をレビューする会
    通称「レビューのレビュー会」を
    ⽉1回やることになった
    

    View Slide

40. 「レビューのレビュー会」
    の開催⽅法は︖
    

    View Slide

41. カレンダーに⽉1の繰り返し予定を⼊れる
    参加メンバーはチームのライター全員
    

    View Slide

42. 「レビューのレビュー会」でやること
    1. Discussion itemsについて話し合う
    2. Hotfixを確認する
    3. Next actionsを決める
    

    View Slide

43. レビュー指摘の中で
    ⽅針が決まっていないものがあったら
    レビューのレビュー会⽤の
    Discussion itemsに書いておく
    

    View Slide

44. 1ヶ⽉の間に結構な数の
    「⽅針が決まっていなかったこと」
    が溜まるので
    レビューのレビュー会で
    全員で⽅針を決めていく
    

    View Slide

45. 直近1ヶ⽉の間に発⽣した
    Hotfixも確認して
    「こういう観点でレビューしないと
    こういう⾒落としがあるんだね」
    も全員で共有する
    

    View Slide

46. ⽅針が決まったら
    「チームのライティングルールに追記する」
    「⽅針に従って⼀⻫修正するチケットを作る」
    みたいなNext actionを書いて終わる
    

    View Slide

47. 「レビューのレビュー会」誕⽣以前︓
    レビュー指摘の中で
    ⽅針が決まっていないものがあったら
    →決まるまで進めない
    

    View Slide

48. 「レビューのレビュー会」誕⽣後︓
    レビュー指摘の中で
    ⽅針が決まっていないものがあった
    →Discussion itemsに積んでおいて
    さっとリリースに進める
    

    View Slide

49. Discussion itemsに積むことで
    次のレビューのレビュー会までは
    いったん忘れてていいや︕
    と安⼼して棚上げできるようになった
    

    View Slide

50. レビューのレビュー会の
    Discussion itemsから
    ⼀部をご紹介
    

    View Slide

51. • 画像ファイルの命名規則
    • Prettierをかけるタイミングはいつか
    • 全⾓数字が残っていたので撲滅するか
    • 英語で箇条書きの末尾にピリオドを書くか
    • 実際のUIテキストやボタン、タブなどを表す表現について
    • 英語で⽂中の「unicode」は先頭⼤⽂字︖⼩⽂字︖
    • 「Japanese only」という表現は避けるべきか
    • レスポンスのJSONで含まれないこともあるプロパティをなんと呼ぶ︖
    • PCで使えるLINEの呼称について
    • ニュースにつける「⾮推奨」と「サポート終了」のタグについて
    • 400番台のエラーを返す時の書き⽅
    

    View Slide

52. • 環境ごとの⼿順はどこまでサポートするか
    • 「公開」と「開⽰」の使い分け
    • AIファイルの管理ルールについて
    • アドモニションにするしない問題
    • 「紐付け」or「紐づけ」
    • 障害対応の進め⽅
    • ⽂字数は「多い/少ない」か「⼤きい/⼩さい」か
    • LINE Seedが作図のフォントに使えそう
    • 多⾔語化 vs 国際化
    • FAQのQの末尾は「︖」で締めるべきか
    • ⽇時の統⼀ルール
    

    View Slide

53. 最初の頃はDiscussion itemsが
    毎回7、8個はあったけど
    段々整備されてきて
    最近は1、2個だったり
    何もなくてスキップになることもある
    

    View Slide

54. 「レビューのレビュー会」で
    レビューの⼯程にあった
    「苦しさ」が解決できた
    

    View Slide

55. 1:
    ドキュメントレビューの苦しさを解決する
    「レビューのレビュー会」
    2:
    テクニカルライターが
    GPT-3 を使ってみた話
    3: Questions and Answers
    9th March 2023 19:00-21:00
    LINE Technical Writing Meetup vol. 22
    

    View Slide

56. 1:
    ドキュメントレビューの苦しさを解決する
    「レビューのレビュー会」
    2:
    テクニカルライターが
    GPT-3 を使ってみた話
    3: Questions and Answers
    9th March 2023 19:00-21:00
    LINE Technical Writing Meetup vol. 22
    

    View Slide