eli5

eli5

このコードをまったく知らない人にもわかるように説明します。まず一文で伝え、そのあと全体像が見えるまで、一度に一つずつ説明します。読者はすでに各部分を知っている状態になります。

何も知らない読者は、図を一度に理解できません。理解できるのは、二つの箱と一本の矢印です。だからキャンバスは二つの箱から始まり、少しずつ大きくなります。全体像を目にするのは最後で、その時点では新しい情報は何もありません。

グラフドキュメントを一つ書きます。そのビューは段階的に大きくなる図で、ウォークスルーはそれらを順に再生し、PR Lens が描画します。読者はリンクを開いて再生ボタンを押します。ページも、一覧も、段落もありません。

必要なもの

PR Lens のマニュアルとリファレンスページです。PR Lens CLI で両方を表示できます。npx @coldtea/pr-lens-cli@latest skill を実行し、続けて npx @coldtea/pr-lens-cli@latest skill references を実行して、最初のドキュメントを書く前に両方を読んでください。このページで Override と記された箇所を除き、マニュアルのルールに従います。

操作マニュアル

1. まず答えを書きます。 コードの機能を人に向けて48文字以内で言えるまで読み込みます。この一文はウォークスルーの見出しにもなり、見出しは48文字までだからです。文字数を数えてください。

   • 機能やコマンドの場合：「あなたが___すると、このコードは___します。」例：「送信を押すと、全員にメールが届きます。」
   • コードベース全体の場合：その製品が何のためのものかを書きます。例：「BestRegards はあなたに代わってニュースレターを送ります。」一つの処理経路ではなく、製品についての文にしてください。 Override、summary。 この一文はドキュメントの summary にもなります。リファレンスでは変更内容を段落で説明しますが、eli5 ではこの一文を使います。

2. 処理経路に絞ります。 機能の場合、入力から出力までの一つの経路をたどります。コードベース全体の場合は、まず製品を使う人が行うことを3～5個挙げ、そのあと中心となるもの、つまり製品名の由来や売り文句になっている機能、または最も多くのコードが関わる機能の経路をたどります。その経路上の部分を図にします。ノードは4～10個、レーンは2～5個です。ヘルパー、設定、型、テストは含めません。同じコードに合流する入口が複数ある場合は、合流点を描き、本文に両方の名前を記載します。一方を省略してはいけません。

3. .pr-lens/graph.json を書きます。 references/graph-document.md に従い、さらに次のルールを守ります。

   • Override、provenance。 スキーマで必須です。git remote get-url origin からリモートを取得します。https://github.com/acme/mail.git と [email protected]:acme/mail.git は、どちらも { "owner": "acme", "name": "mail", "host": "github.com" } になります。現在の HEAD の sha を base.sha と head.sha の両方に設定します。「二つのコミットが同じパッチ」というパーサールールは provenance ではなく patch に関するものなので、これは検証に合格します。
   • レーンは、読者がイメージできる場所を、処理経路の順に左から右へ並べたものです。「あなたのブラウザー」「ウェブサイト」「メール会社」「あなたのメールソフト」のようにします。フォルダーツリーではありません。order を設定します。処理経路がデータベースやキューに複数回触れる場合、それは処理経路上の場所ではありません。それを所有するコードのレーンに配置します。
   • 最初のノードは読者、または読者が触れるものにします。「あなたがメールを書く」のようにします。最初の図に読者自身が登場していなければなりません。人物には kind: "external" を使います。スキーマには人物の種類がありません。
   • ノードの label は、その部分が行うことを3語以内で表します。実際の名前は subtitle に、ファイルは files に記載します。
   • Override、deltas。 対象がプルリクエストでない限り、すべての delta は unchanged にします。
   • stats は不要です。数える差分がありません。
   • emphasis: "hero" のエッジは一つだけにします。答えの一文が説明する受け渡し、つまり削除するとその一文が成り立たなくなるエッジです。処理経路上のすべてのエッジに animated: true を設定します。
   • 処理経路が順序のある一連の流れであれば、通常はそうなりますが、フローを一つ設定します。フローのステップラベルには、渡されるものをわかりやすい言葉で記します。

4. 拡大していくビューを作成します。 ビューを上書きします。 これは、pr-lens スキルの C4 判定ツリーを置き換えます。eli5 ビューは、掘り下げるのではなく、同じ図が成長していくものです。

   • ビュー 1 には、読者と読者が最初に触れる部分の 2 つのノードと、それらをつなぐエッジを含めます。スコープは { "kind": "selection", "nodes": [...], "edges": [...] } です。
   • 次の各ビューには、直前のビューに含まれていたすべての要素に加えて、経路上の新しいノードを 1～3 個と、それらの間のエッジを含めます。1 つのビューに新しい部分を 3 つより多く追加してはいけません。例外は、以下のコードベースビューだけです。
   • 最後のアーキテクチャビューには全体を含めます。"scope": { "kind": "all" } とします。"defaultOpen": true にするのはこのビューだけです。その直前の拡大ビューには、少なくとも 1 つのノードを含めないでください。そうすれば 2 つのビューが同じ図にならず、ノードが同じビューを 2 つ作らないという pr-lens のルールも守れます。ビューを上書きします。 拡大ビューの大半のノードが重複するのは意図的です。異なる必要があるのは最後の 2 つだけです。
   • コードベース全体の場合、ビュー 2 には、読者とプロダクトが行う 3～5 個のことを、プロダクトのレーンにあるノードとして含めます。このビューには最大 5 つの部分を追加できます。これらは経路ではなくリストです。ビュー 3 以降でメインの経路を拡大していきます。それ以外の要素も図に残し、読者が存在を把握できるようにします。
   • 1 つのデータフローのルートは、そのフローにスコープを設定します。"scope": { "kind": "selection", "flows": ["<flow id>"] } とします。これがないと、フローは描画されません。
   • すべてのビューをルートにします。ネストしないでください。
   • ビュー名には、そのビューに含まれるものを使います。you-and-the-editor、plus-the-queue、the-whole-thing のようにします。

5. ウォークスルーを作成します。拡大ビューごとに 1 ステップ、次にフロー、最後に全体を説明します。 まず数えます。拡大ビューの数に、フローの 1～2 ステップと最後の締めくくりの 1 ステップを足し、合計を最大 9 ステップにします。ノードが 10 個なら、拡大ビューは 3～5 個になります。一度に 1 つではなく、2～3 個ずつ増やしてください。

   • 見出しを上書きします。 見出しには、何が変わったかではなく、何が起こるかを書きます。「ウェブサイトがメールをまとめます」のようにします。ステップ番号は付けません。キャンバスが数えます。
   • body は 140 文字以内の 1 行にします。賢い 12 歳の子どもが一度読めばわかる内容にしてください。何が起こるか、次にそれが何を意味するかを書きます。数字は算用数字で表します。
   • ステップ 1 ではビュー 1 を表示し、フォーカスは省略します。見出しには答えとなる文を書き、本文では 2 つの部分を紹介します。「これがあなたと、文章を書く画面です。すべてはここから始まります。」
   • 次の各ステップでは、次の拡大ビューを表示し、新しいノードだけに { "kind": "selection", "nodes": [...] } でフォーカスします。本文では、新しい部分の役割だけを説明します。
   • 最後の拡大ビューの後、{ "kind": "flow", "flow": "<id>" } でフローを表示し、順序をたどる 1～2 ステップを設けます。messages にフォーカスします。問題が起きる箇所は、これらのステップの 1 つに、淡々とした言葉で記述します。ハッピーパスのフローには、それ自体の失敗メッセージがないため、失敗の直前にあるメッセージにフォーカスします。失敗メッセージを作り出してはいけません。
   • 全体ビューには 2 つのステップを設けます。1 つ目では、そのビューで追加されたノードをフォーカスして紹介し、最後のステップで締めくくります。締めくくりのステップでは全体ビューを表示し、フォーカスは省略します。見出しには再び答えとなる文を書き、本文には読者が理解した数字を 1 つ加えます。「メール 1 通が入り、2,000 通のメールと 1 件の Postmark へのリクエストになります。」

6. 検証し、描画し、プッシュします。

   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json
   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light
   npx @coldtea/pr-lens-cli@latest canvas push .pr-lens/<drawing>/drawn.graph.json
   

   render は、描画先のフォルダーを出力します。フォルダー名はドキュメントのタイトルに基づきます。そのフォルダーにある drawn.graph.json をプッシュします。.pr-lens/ に複数の描画データがあると、引数なしの canvas push は停止します。

   すべての失敗を修正し、再度検証します。失敗が指摘した要素を削除せず、参照を修正してください。canvas push はビューへのリンク https://prlens.dev/c/{id} と埋め込みリンクを出力します。ビューへのリンクが成果物です。

7. 開いて終了します。 このハーネスでブラウザーを開ける場合は、ビューへのリンクを開きます。答えとなる文とリンクを、2 行で返信します。それ以外は何も書きません。ステップのリスト、ファイルのリスト、作業内容の要約も不要です。依頼者がレポートや比較を求めている場合は、それは 2 つ目の依頼であり、今回の依頼への回答後に対応します。 キャンバスについての追加質問には、キャンバス上で回答します。npx @coldtea/pr-lens-cli@latest canvas open .pr-lens/<drawing>/drawn.graph.json を一度実行し、その後、pr-lens スキルの「開いたキャンバスの横で回答する」にあるとおり、同じパスを指定して --drawing を付けた canvas answer を実行します。ここでも同じ平易な言葉を使ってください。

言葉

平易な言葉だけを使ってください。使用しない言葉：活用する、オーケストレーションする、パイプライン、抽象化、ハンドラー、ラッパー、レイヤー、ユーティリティ、呼び出す、インスタンス化する。何をするのかをそのまま説明してください。実際の名前はそれぞれ一度だけ、サブタイトルに登場させ、コードを見たい読者が見つけられるようにします。

読者がエンジニアではなく、日常の何か一つが手順と最初から最後まで一つずつ対応する場合は、たとえを使ってもかまいません。本文で使い、ラベルでは使わないでください。最後の手順ではたとえを使わず、実際のものを示してください。

これは何ではないか

レビューでも、ファイル一覧でも、チュートリアルでも、アーキテクチャ文書でもありません。バグ、リスク、意見を記載する欄はなく、段落もありません。また、全体を一枚の大きな図で一度に示すことはありません。