最近Issueがわかりづらいなあと思うことが多くて、以下のTweetに感化されて自分が普段Issueを書くときに考えていることをまとめてみたいなと思った
技術力の向上に、issueをちゃんと書けるになる訓練をするのが良いのではと思った - Magnolia Tech https://t.co/6ckr2Mwf8j
— magnoliak🍧 (@magnolia_k_) March 25, 2022
最近考えてたことだ
— Daisuke Tsuji🍿 (@dim0627) March 26, 2022
直接的に伝える文章より、間接的に誰かが見る文章のほうが親しみがないのでうまく出来ない人が多い印象 https://t.co/POiwwL4w9o
ここでいうIssueはOSSのものではなくて、仕事でプロダクト開発をするという体のものを指してます
「CSVエクスポートできるようにする」みたいなタイトルではなく「ユーザーは注文一覧画面から注文をCSVエクスポートできる」のように「ActorはWhatができる」のようにストーリーベースで書くようにしてる
タイトルから「完了した状態」をわかるようにする、という言い方がわかりやすいかも
個人的な経験上、本文は空っぽだったり議論がだらーっと書いてあったりすることが多かった
だけど、空っぽならまだしも議論が書いてあると結論がわからないしリーディングコストがかかるのでできれば避けたいと思ってる
そのIssueを完遂（タイトルの状態を満たす）するのに必要な情報かどうか？というのを考えているという表現が正しいかも
経緯はSlackであったり口頭の議事がドキュメンテーションツールにあると思うので、本文の末尾にリンクとしてはったりすることが多い
本文はIssueを担当する人が背景を知ることで盲目的に作業するのではない = モチベーションを持ってもらうために、Whyを入れるようにしてる
例えばこんな感じ
## Why
- 顧客のユースケースとしてCSVエクスポートの需要がユーザヒアリングによってわかったため
- ヒアリングのログ: https://example.com
WhyでそのIssueの目的がわかっても、じゃあ実際に何をどう作ればいいのか？というところが詰まっていないので、どういう実現をすればいいのかをHowとして記載する
## How
- 注文一覧画面の上部右端に「CSVエクスポート」のボタンを配置
- 押下したらCSVがダウンロードされる
- UIのイメージ: https://www.figma.com/file/xxxxxxxxxxx
ここはタイトルと情報が重複することがあるけど、タイトルに情報が多いほうがIssue一覧から詳細に行かずにゴールが見えるメリットを優先してる
Howは難しいところで、例えば
など、起票者だけでは拾いきれない、決めきれないことがあったりするので、あまり時間をかけて書ききらずに最低限を書いてスクラムチームでともに作り切るのがいいのでは、というのが現段階の個人的な解という感じ