What problem are we solving?

Many documentation teams remember headings, alt text, and contrast, but forget that examples are content too. A page may look accessible while the most important part — a code example, a response payload, or a reference table — is difficult to read, impossible to understand without syntax colors, or hard to interpret with a screen reader.

A strong article about accessible examples should not only tell the reader to “be careful”. It should demonstrate the pattern inside the article itself. That means each example needs context, expected result, visible structure, and wording that still works when colors or layout cues disappear.

Principles for accessible examples

  1. State the goal before the snippet. Tell the reader what the example does and what success looks like.
  2. Do not rely on syntax colors as meaning. The reader must understand the request, response, or shell output even in plain monochrome text.
  3. Separate success, warning, and error cases. Do not hide meaning only in green or red highlighting.
  4. Use real tables only for real relationships. If the content has columns and headers, present it as a table; if it is a procedure, do not force it into a grid.
  5. Keep one fact per cell and one purpose per example. Dense examples become inaccessible faster than long prose.

Example 1. Explain the goal, then show the request

Before the code block, explain the task in plain language:

Get report 42. Replace <token> with a valid access token. A successful request returns HTTP 200 and a JSON body where status is ready.

Now show the request itself:

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json

Show the successful response as a separate block:

{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}

And show the failure path separately too:

{
  "error": "not_found",
  "message": "Report 42 does not exist or is no longer available."
}

Why is this version more accessible? Because the reader does not need color to understand what is happening. The prose explains the goal, the request is short, and the success and error responses are visually separated and explicitly named.

Example 2. A reference table must carry meaning in headers

Reference tables work well when the column title already tells the reader how to interpret each cell.

Field Type Required Meaning Notes
id integer yes Report identifier Stable value returned in all successful responses
status string yes Processing state Typical values: queued, running, ready, failed
download_url string no Link to the generated file Present only when status is ready
error string no Machine-readable error code Present only in unsuccessful responses

This table works because the reader can understand the relationship by reading the headings. There is no hidden meaning in cell color, diagonal layout, or visual grouping alone.

Here is a compact editorial checklist table for review:

Check Ask this question Good sign
Goal Does the text explain what the example is for? The reader can predict the result before reading the code
Structure Is success shown separately from error? The article has distinct blocks or labels
Table design Do headers define the meaning of each column? Cells can be read independently with the header context
Language Is jargon reduced where possible? The explanation around the example is shorter and clearer than the example itself

Example 3. Show the table markup when markup matters

If the article teaches authors how to build a good HTML table, show the markup explicitly:

<table>
  <caption>Report response fields</caption>
  <thead>
    <tr>
      <th scope="col">Field</th>
      <th scope="col">Type</th>
      <th scope="col">Required</th>
      <th scope="col">Meaning</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>yes</td>
      <td>Current processing state</td>
    </tr>
  </tbody>
</table>

This example is useful because it teaches structure, not just appearance. A reader can see the caption, column headers, and row header, and understand why these pieces improve navigation and screen-reader interpretation.

What to avoid

Avoid these patterns, even when the page “looks fine”:

  • a code block dropped onto the page without any explanation;
  • “success” shown only in green and “error” only in red;
  • tables used to lay out process steps or paragraphs of prose;
  • cells full of long notes, mixed units, or multiple independent facts;
  • screenshots of code instead of selectable, copyable text;
  • vague phrases like “returns data” instead of a precise explanation of what fields matter.

A practical authoring pattern

When you add an example to documentation, use this order:

  1. Goal — what the reader is trying to do.
  2. Prerequisite — token, role, environment, or input assumptions.
  3. Example — request, command, snippet, or markup.
  4. Expected result — success response, output, or visible effect.
  5. Failure mode — the most common error the reader must recognize.
  6. Reference table — only when the reader needs to compare fields or values.

That pattern makes examples easier to maintain and easier to consume.

Short editorial checklist

  • Explain the purpose before the code block.
  • Keep success and error examples separate.
  • Make code understandable without syntax colors.
  • Use tables only when rows and columns express a real relationship.
  • Put units, states, and required/optional information in headers or explicit text.
  • Prefer copyable text over screenshots of code.
  • Review the page at high zoom and with the expectation that the reader may scan, copy, or listen to the content.