The CLEAR Framework

What this framework is, and what it is not

C — Concise

What it means: the answer to the question a section promises arrives in that section's first sentence or two, and everything after it is elaboration a reader can stop reading. Concise is about information order, not word count. A three-thousand-word page can be concise; a two-hundred-word page that spends its first hundred words establishing that databases are important is not.

Why it matters mechanically: retrieval scores passages against a query. A passage whose opening sentences are generic context ("In today's fast-moving landscape…") is semantically similar to every other page's opening and distinctive of nothing. Worse, when a synthesis step has to pick the sentence that answers the question, front-loaded preamble means the answer sits deep in the passage, competing with sentences that are about the topic in general. Putting the claim first raises the density of the signal in the part of the text most likely to be quoted.

The second version is not shorter by accident — it is shorter because it deleted the sentences that carried no information. Note also what it did not do: it did not drop the detail about sliding windows and excluded endpoints. Concise means the preamble goes, not the substance.

L — Logical

What it means: the page has a hierarchy, the hierarchy is expressed in the markup, and the markup's hierarchy matches the meaning. One h1. h2 for real top-level sections. h3 nested under the h2 it belongs to, never skipping a level to get a smaller font. Lists that are lists. Tables that are tables.

Why it matters mechanically: before a page is embedded or scored, it is converted to text and split into chunks. Heading boundaries are the most common split points, and the heading trail is frequently prepended to each chunk so the passage carries its own context. That means your headings do double duty: they decide where the cuts happen, and they are part of what gets compared to a query. A page built from styled divs has no boundaries to cut on, so the chunker falls back to arbitrary length splits and your carefully separated sections get merged and severed in the wrong places.

<div class="section-title">Authentication</div>
<div class="body">Use a bearer token.</div>
<h4 class="big-heading">Rotating keys</h4>
<p>Generate a new key, then...</p>
<div class="grid">
  <div>Standard</div><div>1,000/min</div>
  <div>Enterprise</div><div>10,000/min</div>
</div>

<h2>Authentication</h2>
<p>Use a bearer token.</p>
<h3>Rotating keys</h3>
<p>Generate a new key, then...</p>
<table>
  <caption>Rate limits by plan</caption>
  <thead>
    <tr><th>Plan</th><th>Requests per minute</th></tr>
  </thead>
  <tbody>
    <tr><td>Standard</td><td>1,000</td></tr>
    <tr><td>Enterprise</td><td>10,000</td></tr>
  </tbody>
</table>

Logical also covers ordering. Group what belongs together; do not scatter three parts of one procedure across a page because the layout looked better that way. Within a section, move from the general statement to the specific case, and keep any sequence in sequence — a prerequisite listed after the step that needs it is a defect regardless of who is reading.

E — Explicit

What it means: nothing load-bearing is left to inference. Pronouns resolve within the sentence or the one before it. Numbers carry units, currencies and dates. Terms are defined where they are first used. Comparisons name what they compare against. A section does not depend on a paragraph three screens up.

Why it matters mechanically: this is the property that most directly serves passage-level retrieval. Your page is not retrieved as a page; a chunk of it is retrieved on its own, without its neighbours. Every implicit dependency in that chunk — "as described above", "this approach", "it is 40% faster" — becomes either an unresolvable reference or, worse, a resolvable-but-wrong one when a synthesis step guesses at the antecedent. Explicit writing is what makes a passage true in isolation.

A caution that belongs here rather than in the pitfalls section, because it is the most common way Explicit goes wrong: being explicit means naming the subject when the reference would otherwise be ambiguous. It does not mean repeating your product name in every sentence. Prose that reads "Example API rate limits let Example API users limit Example API requests" is not explicit; it is keyword stuffing wearing a framework as a disguise, and it degrades the text for every reader including the machine ones.

A — Accessible

What it means: the content can actually be obtained and read by a non-browser client. That is three separate things: it is reachable (not blocked, not behind an interstitial, not gated), it is present in the served HTML (not assembled by client-side JavaScript), and its meaning survives being reduced to text (alt text on informative images, real text instead of text-in-images, transcripts for media, table semantics rather than visual columns).

Why it matters mechanically: most content fetchers do not execute JavaScript. If your article body arrives via a client-side fetch, the retrieved document is your shell — navigation, footer, a loading state — and that is what gets embedded. This is a binary failure, not a degradation: it does not matter how concise and explicit the prose is if the prose is not in the response.

It is worth being clear that Accessible in CLEAR overlaps heavily with accessibility in the human sense, and the overlap is not a coincidence. Alt text, semantic landmarks, real headings, captions and transcripts exist because a screen reader also consumes a linearized text stream with no visual layout. The work you do for assistive technology is largely the same work, which makes this the letter with the best independent justification.

# Is the content in the response, before any JS runs?
curl -sL https://example.com/docs/rate-limits | grep -c "1,000 requests per minute"

# Roughly what a fetcher sees after conversion to text
curl -sL https://example.com/docs/rate-limits \
  | python3 -c "import sys,html,re; t=sys.stdin.read(); \
t=re.sub(r'(?s)<(script|style).*?</\1>','',t); \
print(html.unescape(re.sub(r'<[^>]+>',' ',t)))" | tr -s ' \n'

R — Referenceable

What it means: if something wants to cite you, everything it needs is present and stable. A canonical URL that does not change. Anchor targets on headings so a specific claim can be linked, not just the page. A named author. Honest published, modified and — where relevant — reviewed dates. Sources named in the prose, not hidden inside anchor tags. An organization that resolves to a known entity.

Why it matters mechanically: a generative answer that cites you has to produce a URL, and often an attribution. If the passage it used carries no provenance, the system either drops the citation or asserts the claim unattributed — neither of which does you any good. And a URL that has moved twice since it was indexed is a citation that lands on a redirect chain or a 404, which is a reputational cost paid by both parties.

End to end: one page, five passes

The letters are easier to apply in sequence than all at once. Below is a real-shaped documentation page — how to rotate an API key — taken through one pass per letter. Nothing is invented at the last step that could have been fixed at the first; each pass does one job.

<div class="hero-title">Key Management Made Simple</div>
<div class="lede">
  Security is more important than ever in today's threat landscape.
  That's why we've built a powerful and flexible key management
  experience designed to keep your integration safe. Rotating your
  credentials regularly is widely considered a best practice.
</div>

<div class="h-large">Getting started</div>
<div class="body">
  It's easy. Head to the dashboard and you'll find everything you need
  under settings. From there you can create a new one and swap it in.
  Make sure to do this before the old one expires or you may experience
  disruption. Most customers find the process takes just a few minutes.
</div>

<img src="/img/rotation-steps.png">

<div class="h-large">Notes</div>
<div class="body">
  As mentioned above, timing matters. The overlap period is generous.
  See the docs for more details.
</div>

Rotating an API key

Create a new key in the dashboard, deploy it, then revoke the old one.
Both keys work during the overlap period, so rotation causes no downtime.

<h1>Rotating an API key</h1>
<p>Create a new key in the dashboard, deploy it, then revoke the old one.
   Both keys work during the overlap period, so rotation causes no downtime.</p>

<h2 id="before-you-start">Before you start</h2>
<ul>...</ul>

<h2 id="steps">Rotation steps</h2>
<ol>
  <li>...</li>
</ol>

<h2 id="verifying">Verifying the rotation</h2>
<h2 id="rollback">If something breaks</h2>
<h2 id="faq">Common questions</h2>

<h2 id="before-you-start">Before you start</h2>
<ul>
  <li>You need the <strong>Admin</strong> role. Members cannot create or
      revoke keys.</li>
  <li>Know every service using the current key. List them with
      <code>GET /v1/keys/{id}/usage</code>, which returns the client IDs
      seen in the last 30 days.</li>
</ul>

<h2 id="steps">Rotation steps</h2>
<ol>
  <li>In Dashboard &rarr; Settings &rarr; API keys, choose
      <strong>Create key</strong>. The new key is shown once; it cannot
      be retrieved later.</li>
  <li>Deploy the new key to every service found above. Both the old and
      new key authenticate successfully during the overlap period.</li>
  <li>Confirm zero requests on the old key for 24 hours using the usage
      endpoint, then choose <strong>Revoke</strong> on the old key.</li>
</ol>
<p>The overlap period is <strong>7 days</strong> from the moment the new
   key is created. After 7 days the old key stops authenticating whether
   or not you have revoked it, and requests using it return
   <code>401 key_expired</code>.</p>

<!-- The diagram now illustrates the text instead of carrying it -->
<img src="/img/rotation-timeline.png"
     alt="Timeline: new key created on day 0, both keys valid through
          day 7, old key stops authenticating on day 8.">

<!-- Server-rendered, not fetched client-side -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Rotating an API key",
  "totalTime": "PT10M",
  "step": [
    { "@type": "HowToStep", "name": "Create a new key",
      "text": "In Dashboard > Settings > API keys, choose Create key.",
      "url": "https://example.com/docs/key-rotation#steps" },
    { "@type": "HowToStep", "name": "Deploy the new key",
      "text": "Deploy the new key to every service using the old one." },
    { "@type": "HowToStep", "name": "Revoke the old key",
      "text": "After 24 hours with zero requests on the old key, revoke it." }
  ]
}
</script>

<link rel="canonical" href="https://example.com/docs/key-rotation">

<p class="byline">
  Written by <a href="/authors/[author-slug]" rel="author">[Full Name]</a>,
  [Role].
  Published <time datetime="2026-01-15">15 January 2026</time>.
  Last substantive update <time datetime="2026-06-02">2 June 2026</time>
  (overlap period changed from 3 to 7 days in release 4.2).
  Reviewed <time datetime="2026-08-11">11 August 2026</time>.
</p>

Common pitfalls

Each letter has a characteristic way of being over-applied. These are the failures that come from taking the framework seriously and running past the point where it helps.

Next steps: score a single page against the AXO scoring rubric, run a site-wide pass with the audit checklist, or read agent interaction patterns for the pipeline mechanics that most of these rules follow from.