最近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を入れるようにしています。
例えばこのような感じです。
1## Why 2 3- 顧客のユースケースとしてCSVエクスポートの需要がユーザヒアリングによってわかったため 4- ヒアリングのログ: https://example.com
WhyでそのIssueの目的がわかっても、実際に何をどう作ればいいのかというところが詰まっていないので、どういう実現をすればいいのかをHowとして記載します。
1## How 2 3- 注文一覧画面の上部右端に「CSVエクスポート」のボタンを配置 4- 押下したらCSVがダウンロードされる 5- UIのイメージ: https://www.figma.com/file/xxxxxxxxxxx
ここはタイトルと情報が重複することがありますが、タイトルに情報が多いほうがIssue一覧から詳細に行かずにゴールが見えるメリットを優先しています。
Howは難しいところで、例えば
など、起票者だけでは拾いきれない、決めきれないことがあったりするので、あまり時間をかけて書ききらずに最低限を書いてスクラムチームでともに作り切るのがいいのではないか、というのが現段階の個人的な解という感じです。
blog.unresolved.xyz