Какую проблему мы решаем?

Команда может помнить про заголовки, alt-текст и контраст, но забывать, что примеры — это тоже контент. Страница выглядит аккуратно, а самый важный фрагмент — код, JSON-ответ или таблица полей — оказывается трудным для чтения, непонятным без цветов подсветки или неудобным для screen reader.

Хорошая статья о доступных примерах не ограничивается советом «будьте внимательнее». Она сама показывает правильный паттерн внутри текста. Значит, у каждого примера должны быть контекст, ожидаемый результат, явная структура и формулировки, которые сохраняют смысл даже тогда, когда пропадают цветовые и визуальные подсказки.

Принципы доступных примеров

  1. Сначала назовите цель. Читатель должен понять, что делает пример и как выглядит успешный результат.
  2. Не опирайтесь на цвет как на смысл. Запрос, ответ или вывод команды должны быть понятны и в монохромном виде.
  3. Разделяйте успех, предупреждение и ошибку. Не прячьте смысл только в зелёной или красной подсветке.
  4. Используйте таблицы только для табличных отношений. Если материал состоит из столбцов и заголовков — это таблица. Если это процедура, не надо насильно превращать её в сетку.
  5. Один факт в ячейке, одна задача в примере. Плотные и перегруженные примеры теряют доступность быстрее любого длинного абзаца.

Пример 1. Сначала объясните задачу, потом показывайте запрос

Перед кодовым блоком коротко объясните цель:

Получите отчёт 42. Замените <token> действующим access token. При успешном запросе сервер вернёт HTTP 200 и JSON, где status равен ready.

После этого покажите сам запрос:

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": "Отчёт 42 не существует или больше недоступен."
}

Почему этот вариант доступнее? Потому что читателю не нужно угадывать смысл по цвету. Текст заранее задаёт цель, запрос короткий, а успешный и ошибочный сценарии явно разделены и названы.

Пример 2. Справочная таблица должна нести смысл через заголовки

Справочная таблица хороша тогда, когда заголовок столбца уже помогает интерпретировать каждую ячейку.

Поле Тип Обязательно Значение Примечание
id integer да Идентификатор отчёта Возвращается во всех успешных ответах
status string да Состояние обработки Типичные значения: queued, running, ready, failed
download_url string нет Ссылка на готовый файл Появляется только при status = ready
error string нет Машинно-читаемый код ошибки Есть только в неуспешных ответах

Эта таблица работает, потому что связь читается из заголовков. Смысл не спрятан в цвете ячейки, положении столбца или декоративной группировке.

Ниже — компактная редакционная таблица для самопроверки:

Проверка Вопрос Хороший признак
Цель Понятно ли, зачем нужен пример? Читатель может предсказать результат до чтения кода
Структура Разделены ли успех и ошибка? В статье есть отдельные блоки или явные подписи
Таблица Определяют ли заголовки смысл столбцов? Ячейку можно понять вместе с её заголовком
Язык Не сложнее ли пояснение, чем сам пример? Текст вокруг примера короче и яснее самого фрагмента

Пример 3. Если важна разметка таблицы — показывайте и разметку

Если статья учит автора собирать хорошую HTML-таблицу, покажите код напрямую:

<table>
  <caption>Поля ответа отчёта</caption>
  <thead>
    <tr>
      <th scope="col">Поле</th>
      <th scope="col">Тип</th>
      <th scope="col">Обязательно</th>
      <th scope="col">Значение</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>да</td>
      <td>Текущее состояние обработки</td>
    </tr>
  </tbody>
</table>

Такой пример полезен тем, что обучает структуре, а не только внешнему виду. Читатель видит caption, заголовки столбцов и заголовок строки и понимает, почему эти элементы улучшают навигацию и восприятие таблицы.

Чего лучше избегать

Даже если страница «выглядит нормально», избегайте таких паттернов:

  • кодовый блок без объяснения цели;
  • «успех» только зелёным, а «ошибка» только красным;
  • таблицы, в которые упакованы шаги процедуры или длинные абзацы;
  • ячейки с несколькими независимыми фактами, смешанными единицами и длинными примечаниями;
  • скриншоты кода вместо копируемого текста;
  • расплывчатые формулировки вроде «возвращает данные» без объяснения, какие поля действительно важны.

Рабочий авторский шаблон

Когда вы добавляете пример в документацию, используйте такой порядок:

  1. Цель — что именно пытается сделать читатель.
  2. Предпосылка — токен, роль, среда, входные условия.
  3. Пример — запрос, команда, фрагмент кода или разметки.
  4. Ожидаемый результат — успешный ответ, вывод или заметный эффект.
  5. Неуспешный сценарий — самая частая ошибка, которую читатель должен узнать.
  6. Справочная таблица — только если нужно сравнить поля, значения или состояния.

Такой порядок одновременно улучшает понятность и снижает стоимость сопровождения: редактору легче обновлять отдельный сценарий, а читателю — быстрее находить нужный фрагмент.

Короткий редакционный чек-лист

  • Объясните цель до кодового блока.
  • Разделите успешный и ошибочный сценарии.
  • Сделайте код понятным без подсветки синтаксиса.
  • Используйте таблицу только там, где строки и столбцы действительно выражают отношение данных.
  • Выносите единицы измерения, состояния и обязательность в заголовки или явный текст.
  • Предпочитайте копируемый текст скриншотам кода.
  • Проверяйте страницу так, как её реально будут использовать: в масштабе, при сканировании глазами, при копировании фрагментов и при последовательном чтении.

Связанные материалы