Welches Problem lösen wir?

Ein Team denkt an Überschriften, Alt-Text und Kontrast, vergisst aber leicht, dass Beispiele ebenfalls Inhalt sind. Die Seite wirkt ordentlich, doch gerade der wichtigste Teil — Codebeispiel, JSON-Antwort oder Referenztabelle — kann schwer lesbar sein, zu stark von Farbe abhängen oder für Screenreader unpraktisch werden.

Eine gute Anleitung sagt nicht nur „seid vorsichtig“, sondern zeigt das richtige Muster im Artikel selbst: Kontext, erwartetes Ergebnis, klare Struktur und Formulierungen, die auch ohne Farben funktionieren.

Prinzipien für barrierefreie Beispiele

  1. Das Ziel vor dem Codeblock nennen.
  2. Farbe nicht als einzigen Bedeutungsträger verwenden.
  3. Erfolg, Warnung und Fehler trennen.
  4. Tabellen nur für echte tabellarische Beziehungen verwenden.
  5. Eine Aussage pro Zelle, ein Hauptzweck pro Beispiel.

Beispiel 1. Erst die Aufgabe erklären, dann die Anfrage zeigen

Bericht 42 abrufen. Ersetzen Sie <token> durch ein gültiges Zugriffstoken. Bei Erfolg liefert der Server HTTP 200 und ein JSON, in dem status den Wert ready hat.

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}
{
  "error": "not_found",
  "message": "Bericht 42 existiert nicht oder ist nicht mehr verfügbar."
}

Beispiel 2. Die Tabellenköpfe müssen Bedeutung tragen

Feld Typ Pflicht Bedeutung Hinweis
id integer ja Kennung des Berichts In allen erfolgreichen Antworten vorhanden
status string ja Verarbeitungszustand Typische Werte: queued, running, ready, failed
download_url string nein Link zur Datei Nur vorhanden, wenn status ready ist
error string nein Fehlercode Nur in fehlerhaften Antworten
Prüfung Frage Gutes Zeichen
Ziel Ist der Zweck des Beispiels klar? Das Ergebnis ist vor dem Code nachvollziehbar
Struktur Sind Erfolg und Fehler getrennt? Es gibt eigene Blöcke oder Beschriftungen
Tabelle Definieren die Kopfzeilen die Bedeutung? Die Zelle ist mit ihrer Überschrift verständlich
Sprache Ist die Erklärung klar und knapp? Der Text hilft dem Beispiel

Beispiel 3. Wenn Struktur wichtig ist, zeigen Sie das Markup

<table>
  <caption>Felder der Berichtsantwort</caption>
  <thead>
    <tr>
      <th scope="col">Feld</th>
      <th scope="col">Typ</th>
      <th scope="col">Pflicht</th>
      <th scope="col">Bedeutung</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>ja</td>
      <td>Aktueller Verarbeitungszustand</td>
    </tr>
  </tbody>
</table>

Was man vermeiden sollte

  • Codeblöcke ohne Kontext;
  • Erfolg oder Fehler nur über Farbe;
  • Tabellen für Prozessschritte oder lange Absätze;
  • mehrere unabhängige Fakten in einer Zelle;
  • Screenshots von Code statt kopierbarem Text.

Praktisches Autorenmuster

  1. Ziel.
  2. Voraussetzung.
  3. Beispiel.
  4. Erwartetes Ergebnis.
  5. Häufiger Fehler.
  6. Referenztabelle, falls nötig.

Kurze redaktionelle Checkliste

  • Zweck vor dem Beispiel erklären.
  • Erfolg und Fehler trennen.
  • Code auch ohne Farben verständlich machen.
  • Tabellen nur für echte Zeilen-Spalten-Beziehungen nutzen.
  • Kopierbaren Text statt Codebilder bevorzugen.

Verwandte Materialien