Issue 202

This issue checks whether a page that presents itself as a how-to marks its steps up as steps.

A page titled "How to install the CLI" promises a sequence. An <ol> says "these are ordered steps" in markup; HowTo structured data says the same thing explicitly. Steps told only in prose paragraphs are a sequence the reader has to assemble.

A passing implementation uses an ordered list, or declares HowTo schema. A failing one describes the procedure in prose with neither.

Example: "How to install the CLI" with <ol><li>Download the installer</li><li>Run it</li><li>Verify with cli --version</li></ol> passes. The same instructions as three paragraphs fails.

Steps are a structure engines render. Ordered lists and HowTo markup are what let an assistant answer "how do I install this" as a numbered sequence instead of a wall of text. Prose steps usually get summarised into one lossy sentence.

Order is meaning in a procedure. "Run the migration, then restart the service" and its reverse are different outcomes. An <ol> encodes that; a paragraph relies on the reader parsing "then".

It is an accessibility fix as much as an AEO one. Screen readers announce "list, 5 items" and let users step through. Prose gives them no such navigation.

It makes omissions obvious. Numbering the steps is how you notice step 4 was never written down.

1. Split the procedure into discrete actions. One thing the reader does per step.

2. Use <ol>, not <ul> and not manual numbering. Typing "1." at the start of paragraphs produces text that looks ordered and is not marked as ordered. An unordered list is for sets where sequence does not matter.

3. Start each step with the verb. "Download the installer" reads as an instruction; "The installer should be downloaded" does not.

4. Keep detail inside the <li>. Screenshots, code blocks and caveats belong inside the step they concern, not in paragraphs between list items — which breaks the list into several lists.

5. Consider HowTo structured data for the full treatment: name, step (as HowToStep entries), and totalTime where it is knowable. PixyScan accepts HowTo schema as satisfying this check on its own.

Note on scope: this check only runs on pages whose own title or <h1> says "how to" or "step by step". It never fires on ordinary content pages.

Failing

<title>How to install the CLI</title>
<h1>How to install the CLI</h1>
<p>First download the installer from the releases page. Once that finishes,
run it and accept the defaults. Finally, confirm everything worked by running
the version command in a new terminal.</p>

Three steps, no step markup.

Passing — ordered list

<title>How to install the CLI</title>
<h1>How to install the CLI</h1>
<ol>
  <li>Download the installer from the releases page.</li>
  <li>Run the installer and accept the defaults.</li>
  <li>Open a new terminal and run <code>cli --version</code> to confirm.</li>
</ol>

Passing — HowTo schema

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Install the CLI",
  "step": [
    { "@type": "HowToStep", "text": "Download the installer." },
    { "@type": "HowToStep", "text": "Run the installer." },
    { "@type": "HowToStep", "text": "Run cli --version to confirm." }
  ]
}
</script>

Not evaluated

<title>Pricing</title>

No how-to intent, so the check does not run.

PixyScan detects this from the HTML your server returns, without executing JavaScript.

1. Intent gate. The page's <title> and <h1> are read. The check proceeds only if either matches how to or step-by-step / step by step.

2. Substance gate. The page must have at least 150 words of body text.

3. Structure detection. PixyScan looks for either:

   • at least one <ol> element in the body, or
   • a JSON-LD block declaring "@type": "HowTo".

4. Reporting. If the page declares a how-to, has real content, and has neither an ordered list nor HowTo schema, the issue is raised once for the page.

Why the gate matters: without it, this check would demand an ordered list from every page on the site. The gate means a page can only fail if it has already told us it is a procedure.

Limitation: lists rendered by JavaScript after page load are not visible to PixyScan — or to the answer engines this check is about.