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

Slide 1

Slide 1 text

LINE Technical Writing Meetup vol. 22 ドキュメントレビューの苦しさを解決する「レビューのレビュー会」 LINE Corporation Developer Content Team Yoshiko Horikoshi 9th March 2023 19:00-21:00

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

⾃⼰紹介

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

LINE Corporation Developer Content Team

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

https://techbookfest.org/organization/12790004

Slide 10

Slide 10 text

No content

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

今⽇話す内容

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

質問です

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

私はあります︕

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

苦しい︕つらい︕

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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