explain-irl

シナリオでは、ある人を日付順に追い、その対象がその人に何をもたらすのかが読者に伝わるまでを描きます。

1. 対象を選ぶ

呼び出しで指定された対象を使います。指定がなければ、セッション中に最後に挙がった対象を使います。そのメッセージで複数の対象が挙がっている場合は、AskUserQuestion を使ってどれかを尋ねます。

対象が1つ挙がったら完了です。

2. 登場人物と経緯

プロジェクトで使われている語彙に沿って、影響を受ける人を登場させます。たとえば、顧客、編集者、API の呼び出し元です。その人に名前を付け、実単位で開始時点を設定します。件数、サイズ、日付などです。実際の記録が参照できる場合でも、その人とその人に関する値はすべて創作します。

1つの経路を最後までたどるか、1つの要素だけが異なる複数の経路をたどります。

• トレードオフの場合は、選択肢ごとに1つの経路。
• 特定の条件下でのみ発生する問題の場合は、通常の経路と問題が起きる経路を並べます。

各経路を追跡します。その人の入力を結果を決めるコードに通し、各段階でシステムが生成する内容を記録します。条件の発生頻度など、コードが決めるものではない数値は例示として扱い、シナリオ内でそう明記します。

各経路でシステムが生成するすべての数値を追跡し、それ以外の数値をその人の創作した入力として示すか、例示として明記したら完了です。

3. 描写する

会話の中で、/humanize に沿った散文としてシナリオを描写します。原因は、実際に影響が現れるタイミングで、製品に即した表現で示します。「検索インデックスは夜間に再構築されるため、彼女が午前9時に投稿した出品情報は翌日まで見つかりません」のようにします。

対象に合う内容を盛り込みます。

• システムが誤った内容を表示する場合：実際の内容と表示内容の違い、その情報を見て行動したときに何が起きるか、そしてその誤りが顕在化する（誰かが苦情を言う）のか、潜在する（もっともらしく見える数値が報告されない）のか。
• 影響範囲が不確かな問題の場合：条件が発生する頻度と、その見積もりへの確信度。

シナリオがその人に起きることで終わり、置き換える説明がなくても内容が伝わる文章になったら完了です。