フィールドノート Issue
フィールドノート
フィールドノートとは、チケットを解決へと導くまでに辿ったすべての調査経路を記す走り書きの記録です。目的はできるだけ多くのコンテキストを提供することであり、効率的な引き継ぎと非同期コラボレーションを可能にします。
フィールドノートの考え方
フィールドノート には、ログのスニペットやスクリーンショット、コード（または他のプロジェクト内のコードへのリンク）、使用したコマンドとその出力、誤った手がかりやミスステップ、そして最終的に見つかった解決策などの裏付けデータが含まれます。
目的は 可能な限り多くのコンテキスト を、整理されつつもフィルタリングはせずに提供することで、サポートエンジニアが調査の途中から引き継げるようにすることです。
フィルタリングされていない ため、調査によってはすべてを読み込むのに労力が要るかもしれません。調査の過程で 有用 かつ 関連性のある コメントが見つかれば、それらをチケットにコピー＆ペーストして戻すことができます。多くの人にとって、チケットは依然として最も関連性の高いコンテキストの源 です。
調査の場が 2 か所あると混乱を招く可能性があります。それぞれを 1 つの目的 に集中させてください。
- チケット には現在のコンテキストとコミュニケーションがあるべきで、追加するべきものに自信があるときは常に更新するべき場所です
- フィールドノート は現場でのあなたのメモのためのものです。フィルタリングせず、ブレインダンプし、指で考えながら綴ってください
- 時にはチケットが 1 つまたは複数の古いチケットの続きであることがあります。これらをすべて 1 つのフィールドノートにグループ化することで、信頼できる単一の情報源を持てます
GitLab サポートの チケット応答ガイドライン を意識してください。これらはフィールドノート内でも適用されます。フィールドノートは「何が有用で関連しているか」の判断を後に回せるように、または選んだコメントをフィールドノート内のさらに多くのコンテキストで補強できるように保管されます。これは「内部的にトランスペアレント」であるべきです。サポートチームの可能な限り多くの人と共有しつつ、お客様のプライバシーを守るために機密性も保ちます。
GitLab では、サポートが Issue を起票することが奨励されています し、お客様のチケットに対するマージリクエストも同様です。この フィールドノート プロジェクトは、決してそれに代わるものではありません。他の関連プロジェクトで Issue を起票することが適切な場合は、通常のワークフローに従って進め、このプロジェクトのフィールドノート Issue は正しい Issue へのリンクとともにクローズします。
フィールドノート Issue を作成することは、必ずしも他のエンジニアに「助けを求めている」というシグナルになるわけではありません。助けを求めたい場合は、ヘルプの求め方ワークフロー と OOO 引き継ぎワークフローのガイダンスに従ってください。フィールドノートは非同期（や同期！）コラボレーションを大いに促進し、それが目的でもありますが、後のレビューや学びのためのメモを保管することにも価値があります。
フィールドノートのワークフロー
- 担当の ZD チケットが些末でなくなったら、新しいフィールドノートを作成してチケットにリンクしてください。リンク作業を代わりにやってくれて、作成後にフィールドノートの URL もリストしてくれる Zendesk アプリ があります
- Issue 上でお客様のリクエスト／インシデントを調査し、進めるにつれてコメントにメモを取ります
- 調査によっては誤ったスタートや迷走があります。これは問題ありません。常にコメントすること: Issue 内では何もフィルタリングしようとしないでください
- フィールドノートの説明文の更新を忘れずに
- 思いついたら次のステップを追加し、試したらそれを完了としてマークします
- 説明文は、他のサポートエンジニアが参照するための最新サマリーを保つのに良い場所です
fieldnote.mdテンプレートを使う必要はありません。チケットにより合うテンプレートが他にもありますし、自分のテンプレートを追加することも奨励されています
- チケットの定期的な更新を忘れずに
- フィールドノート Issue 内のコメントから出てきた進展を、随時
- チケットの要約／クロージング要約（フィールドノートの説明文をコピー＆ペースト）
- 追加情報のリクエスト、お客様や他のエンジニアによるフォローアップのリクエスト
- お客様からの参考になるメモや新しい情報は、フィールドノートにコピー＆ペーストして戻すべきです
- 新しいトピック（知識領域）が明らかになったらラベルを更新します
- 現在の調査に関連する古いフィールドノートが他にあるかもしれないので、古いノートやラベルを検索してアイデアやコードを探してみましょう
ヒントとコツ
私たちには、チケット要約の追加をサポートエンジニアに定期的にリマインドする Zendesk トリガーと、要約を Public Comment としてアウトラインするマクロがあります。デフォルトの フィールドノート Issue 説明文テンプレートはこれをベースにしており、そういった要約が意味をなすときは Issue の説明文をそのままチケットにコピーできるようになっています
説明文を最新の状態に保ちましょう
フィールドノートの説明文テンプレートは複数あります。ニーズに合うものを選び、自分のテンプレートも追加してみてください
Zendesk のフィールドノートアプリで作成されたフィールドノートは
fieldnote.mdテンプレートを使用しますが、別のテンプレートのほうがチケットに合う場合は変更できますキーワード付きのブラウザブックマークを使いましょう。フィールドノートと GitLab Issue の検索を簡単にするための提案を以下に示します。
キーワード URL fnhttps://gitlab.com/gitlab-com/support/fieldnotes/fnihttps://gitlab.com/gitlab-com/support/fieldnotes/-/issues/%sfnmhttps://gitlab.com/gitlab-com/support/fieldnotes/-/issues/?sort=created_date&state=opened&assignee_username[]=auserglhttps://gitlab.com/gitlab-org/gitlabglihttps://gitlab.com/gitlab-org/gitlab/-/issues/%sGitLab のキーボードショートカットを覚えましょう。
キーシーケンス 動作 /GitLab 内で文字列を検索 ?キーボードショートカットを表示 i新しい Issue を作成 eIssue の説明文を Edit（編集） rReply（コメント追加） r ▲(上矢印)スレッドへの Reply lLabels の変更 g iIssues へ Go g fFiles へ Go g sSnippets へ Go フィールドノート Issue ボードを使いましょう。そこではフィールドノートをステージや興味深いコラボレーションラベルでグループ化して見ることができます。
チケットには担当者（DRI）が 1 人ですが、Issue は複数の担当者がコラボレーションのために割り当てられることを覚えておきましょう。
便利なブラウザプラグイン
ノートテイキングとスキル共有のさらなるアイデア
私たちはノートテイキングについてのメモを フィールドノートプロジェクトの README と、そこから派生したブランチに保管しています。これらはイテレーションで拡大していきます。アイデアの一部を以下に示します。
- 他者から新しいスキルを学ぶためのフラッシュカード
- トピック別に Issue にラベルを付け、他者の問題解決アプローチを発見する
- シニアによるヘルプセッション後の複雑なチケットのフォロースルー
これらは フィールドノートプロジェクト 内でより詳しく探求されています。説明文テンプレートと同様に、このワークフローの精神は規定的ではありません。このアイデアを取り入れて自分のものにしてください。
bfd74782)