html-effectiveness-research

07-research — Research & Learning

"An explainer with collapsible sections, tabbed code samples and a glossary in the margin reads very differently from the same words dumped linearly. The agent can build the scaffolding that makes a new topic navigable."

When to use

User says	Which paradigm to use	Template
"how does rate limit work in this repo"	Feature explainer	Build your own (see below)
"what does the auth flow look like"	Feature explainer	Same as above
"talk about consistent hashing / Raft / token bucket"	Concept explainer	`../../templates/concept.html`
"what is this / how do I understand X"	Depends on depth — a markdown paragraph or the concept explainer	—

Feature explainer = inthis repothe concrete implementation (the user is already inside the repo) Concept explainer = abstract concept(unrelated to a specific repo, needs interactive visualization)

Paradigm 7.1 · Feature explainer

Spatial shape: 4 sections

TL;DR box — one paragraph covering the core mechanism + performance numbers
Numbered request-path steps — 1/2/3/4, each step collapsible to show code
Config tab switching — yaml / route.ts / response three-tab switching
FAQ — <details> list

HTML skeleton：

<aside class="tldr">
  <strong>TL;DR</strong>
  <p>The whole path is ~40 lines and adds about 0.4 ms p50 to every request.</p>
</aside>

<h2>The request path, step by step</h2>
<ol class="steps">
  <li>
    <span class="num">1</span>
    <h3>Identify the caller <code>middleware/ratelimit.ts:21</code></h3>
    <p>The middleware reduces the request to a <code>bucketKey</code>...</p>
    <details><summary>show source</summary>
      <pre><code>...</code></pre>
    </details>
  </li>
  <!-- 步骤 2-4 -->
</ol>

<h2>Configuring a limit on your route</h2>
<div class="tabs" role="tablist">
  <button role="tab" data-tab="yaml" class="active">limits.yaml</button>
  <button role="tab" data-tab="route">route.ts</button>
  <button role="tab" data-tab="resp">response</button>
</div>
<div class="tab-panels">
  <pre data-panel="yaml" class="active"><code>...</code></pre>
  <pre data-panel="route" hidden><code>...</code></pre>
  <pre data-panel="resp" hidden><code>...</code></pre>
</div>

<h2>FAQ</h2>
<details>
  <summary>How do I exempt internal traffic?</summary>
  <p>Set <code>x-acme-internal: 1</code> from the caller; the middleware checks it against mTLS peer name.</p>
</details>

Key JS(tab switching):

document.querySelectorAll('[role="tab"]').forEach(b => b.onclick = () => {
  document.querySelectorAll('[role="tab"]').forEach(x => x.classList.remove('active'));
  b.classList.add('active');
  document.querySelectorAll('[data-panel]').forEach(p => {
    p.hidden = p.dataset.panel !== b.dataset.tab;
    p.classList.toggle('active', !p.hidden);
  });
});

See ../shared/components.html section 7 "Tab strip".

No standalone template (varies by feature shape).

Paradigm 7.2 · Concept explainer

Spatial shape: 4 sections

Hero section — a paragraph of prose that builds intuition ("You have K keys spread across N servers...")
Interactive visualization — SVG/canvas, can add nodes / remove nodes / watch keys move
Comparison table — naive approach vs this approach (4-5 dimensions side by side)
Where you'll meet it — list real-world scenarios

Example: consistent hashing ring

<div class="viz">
  <svg viewBox="-150 -150 300 300">
    <circle r="120" fill="none" stroke="var(--gray-300)" />
    <g id="ring-arcs"><!-- 节点 arcs 由 JS 渲染 --></g>
    <g id="ring-nodes"><!-- 节点圆点 --></g>
    <g id="ring-keys"><!-- key 小点 --></g>
  </svg>
  <div class="ring-controls">
    <div class="stat"><span>nodes</span><output id="n-count">4</output></div>
    <div class="stat"><span>keys</span><output id="k-count">32</output></div>
    <div class="stat"><span>moved on last change</span><output id="moved">—</output></div>
    <button id="add" class="btn primary">+ Add node</button>
    <button id="rm" class="btn ghost">− Remove a node</button>
    <button id="reset" class="btn ghost">Reset</button>
  </div>
</div>

For complete working ring visualization code see ../../templates/concept.html(including hash → angle function, arc calculation, key redistribution tracking).

Reuse essentials：

Copy concept.html once
Replace the SVG part with the visualization for the new concept (state machine / Bloom filter / Raft, etc.)
Replace the control buttons with the actions for that concept
Replace the comparison table with that concept vs the naive approach

Shared principles

Always start with a paragraph of prose that builds intuition— giving a definition right away fails
The visualization must actually be operable— buttons that do nothing = static image = failure
Always show a "naive vs concept" comparison table— readers need to know why they can't use something simpler
"Where you'll meet it" examples must be concrete——Real system names (Dynamo/Cassandra/Envoy), don't write "various distributed systems"

About this skill

When to use

Paradigm 7.1 · Feature explainer

Paradigm 7.2 · Concept explainer

Shared principles