役に立つGitHub Issueは、不具合がまだ画面に出ているうちに書くのが一番です。操作順を覚えていて、変なコンソール行も見えている。前に試した回避策と、直近のリリース後に変わった点も説明できます。
ところがIssue編集画面を開くと、報告は「Safariでログインできない」まで縮みます。
音声入力が助けるのは、この情報の脱落です。曖昧な観察を自動で正確にしてくれるわけではありません。すでに分かっている証拠、順序、制約を、タイトルと一文に圧縮してしまう前に残しやすくします。
GitHub Issueは、バグ、改善、タスクなどを追跡できます。本文にはGitHub Flavored Markdownを使え、見出し、タスクリスト、リンク、コードブロックを置けます。単なる連絡ではなく、別の人が確認し、再現し、完了を判断するための小さな作業記録です。
固定の型はテンプレートに置き、変わる事実を話す
多くのチームで必要な見出しは決まっています。
- 概要
- 再現手順
- 期待結果
- 実際の結果
- 環境
- 受け入れ条件
このラベルを入力すること自体は重くありません。時間がかかるのは、それぞれの下に何が起きたかを思い出す作業です。
実用的なのは、MarkdownのIssueテンプレートをリポジトリに置き、変動する証拠だけを音声入力する分担です。GitHubはMarkdownテンプレートとIssueフォームに対応しているため、編集画面を開いた時点で固定質問を出せます。音声で埋めるのは、その日に変わった事実です。4回目のクリック、ブラウザの版、古いトークン、代わりに表示された画面、修正後に通るべきテストを話します。
テンプレートが形を支えるので、音声が長い独白になるのも防げます。
再現手順には順序と止まる場所が要る
「アップロードが時々失敗する」だけでは、読む側に不明点が残ります。どのファイルか。どの画面か。認証の前か後か。再試行で直るか。失敗時に何が見えるか。
次の順で話し、正常な流れから外れた地点を明確にします。
- 既知の開始状態を言う。
- 実行する操作を言う。
- 重要な操作後に何が表示されるか言う。
- 最初の誤った結果で止める。
- 再現性を加える。
たとえば次のように話します。
プロフィール画像が未設定のログイン済みアカウントから始めます。設定を開き、5メガバイトを超えるPNGを選び、保存を一度押します。進捗バーは100パーセントまで進みますが、エラー表示なしで元の画像に戻ります。再読み込みしても新しい画像は表示されません。小さいPNGでは成功します。
比較対象、見える結果、再現性が一段落に入っています。急いで入力すると最初に削られやすい情報です。
観察と推測を分ける
推測を証拠のように書くと、Issueは調査しにくくなります。
「キャッシュ無効化が壊れている」は原因の仮説です。「アップロードAPIが200を返した後、2回目のリクエストが古い画像URLを返す」は観察です。原因が別にあっても、後者なら確認できます。
音声入力では境界を言葉にします。
- 「確認できたのは」で見えた挙動を示す。
- 「期待していたのは」で前提にした仕様を示す。
- 「現時点の推測は」で仮説を示す。
- 「未確認なのは」で残る問いを示す。
話して説明すると、自分の理解をそのまま原因として入れやすくなります。仮説だと明示すれば、外れてもIssueの価値は残ります。
正確な文字列は入力し、意味を音声で補う
音声は時系列や理由の説明に向いています。一文字ずつが重要な情報には向きません。
次はキーボードで入力または貼り付けます。
- コミットハッシュとIssue番号
- ファイルパスと識別子
- クエリ付きURL
- シェルコマンドと正規表現
- スタックトレースとログ抜粋
- 一桁違うだけのバージョン番号
ログやコードは読み上げず、フェンス付きコードブロックへ貼ります。GitHubではコードブロックを表示でき、言語名を付ければシンタックスハイライトも使えます。空白、記号、行順が証拠になるため、短い原文のほうが口頭の言い換えより確実です。
その周囲を音声で説明します。どこから取ったログか、どの操作で出たか、どの行を見るべきか。キーボードが証拠を守り、音声が意味を残します。
受け入れ条件が完了地点を作る
不具合を正確に説明できても、終了条件が曖昧なIssueは閉じにくいままです。「画像アップロードを直す」だけでは、エラーを表示すればよいのか、大きなファイルを受け付けるのか、再試行するのか、すぐ新画像へ切り替えるのか分かりません。
変更後に確認できる受け入れ条件を加えます。GitHubのタスクリストはMarkdownのチェックボックスなので、作業中も条件を見える状態にできます。
先ほどの例なら次のようになります。
- 対応画像では、手動再読み込みなしで新しい画像が表示される。
- 非対応サイズでは、見えるエラーが表示される。
- 失敗時に既存画像が置き換わらない。
- 回帰テストが失敗したサイズ境界を含む。
「何を見たら直ったと同意できるか」と問い、その答えを話すと作りやすくなります。実装そのものが要件でない限り、手段ではなく結果を書きます。
Cleanは報告を忠実に整え、Rawは話した内容をすべて残す
TalkTalkTypeはOption-Spaceを押している間だけ録音し、離すと、録音開始時にフォーカスしていた入力欄へ結果を返します。GitHub Issueの編集画面なら、リポジトリの情報、テンプレート、既存コメントを見たまま話せます。
Cleanは忠実な軽い整形です。話した言葉、順序、文体、意図した短さを保ち、意味が変わらない明らかな言い淀みだけを除いて一行で返します。報告を別のバグテンプレートへ勝手に変えたり、不足事実を作ったりしません。
Rawは整形を行わず、言い直しを含む全文を残します。後で大きく編集する場合や、整形で変わりそうな珍しい固有名詞を含む場合に向きます。
どちらでも、正確な技術文字列を安心して読み上げられるわけではありません。送信前に下書きを読み、版、名前、パス、数値はコピーした値へ置き換えます。Macのどのアプリでも使える音声入力では、フォーカスした入力欄への貼り付けとクリップボードへの退避を説明しています。
入力しやすくても秘密情報はIssueへ入れない
バグ報告先は、公開リポジトリ、社内の非公開リポジトリ、将来公開される可能性のあるプロジェクトのいずれかです。入力先そのものをデータ境界として扱います。
APIキー、セッションクッキー、アクセストークン、顧客の個人情報、本番認証情報は話さないでください。貼り付けるログもマスキングします。音声入力は入力の負担を下げますが、作成後のIssueを誰が読めるかは変えません。
TalkTalkTypeは、音声、元の文字起こし、整形後テキストをサーバー側の履歴として保存しません。ただし最終テキストはIssue作成時にGitHubへ送信されます。Macのプライベート音声入力では、それ以前の音声と文字起こしの経路を追っています。
後回しにしそうなIssueから始める
不具合をまだ再現できるうちに、リポジトリのIssueテンプレートを開きます。タイトルと正確な識別子は入力し、開始状態、操作順、最初の誤結果、再現性、期待する挙動、未確認事項を一回で話します。
一度読み直し、必要最小限のログを貼り、完了を定義するチェックリストを加えます。
長いIssueを書くことが目的ではありません。その場が過ぎた後でも、別の人が動けるだけの情報を残すことが目的です。