Качество документации

docara qa report проверяет собранный сайт и ставит документации оценку от 0 до 100. Отчёт показывает, какие страницы требуют внимания и что исправить в первую очередь. docara qa review-packet готовит вопросы, на которые программа ответить не может: верно ли написано, понятно ли, решает ли страница задачу. На них отвечает человек или ИИ-помощник.

Обе команды работают без интернета и ничего не меняют в страницах. Docara сама не обращается к ИИ. Один и тот же сайт всегда получает одну и ту же оценку.

Как запустить

Сначала соберите сайт, затем запустите отчёт для той же сборки:

php vendor/bin/docara build production
php vendor/bin/docara qa report --env=production
php vendor/bin/docara qa report --env=production --html --top=15

Отчёт записывается рядом со сборкой, а не в неё: build_production.docara/quality-report.json, а с --html ещё и build_production.docara/quality-report.html. На опубликованный сайт эти файлы не попадают.

Пример вывода:

Documentation quality: 93/100 — 102 page(s) scored, 48 need attention, 15 skipped.

  completeness   83
  freshness      n/a (documentation tracking off)
  findability    93
  readability    95
  accessibility  100
  links          100

Fix first:
  1. +0.07  /ru/components/figure/  QUALITY_DESCRIPTION_MISSING
       No description in front matter or in the page file. Add description: one sentence about what the reader gets from the page.

Biggest gains by check (fixed on every page):
  +2.86  QUALITY_DESCRIPTION_MISSING on 42 page(s)

Report (json): build_production.docara/quality-report.json

Если в проекте есть docara.authoring.json, docara build после сборки печатает одну строку с оценкой:

Documentation quality: 93/100, 48 page(s) need attention (docara qa report --env=production).

Без этого файла сборка ничего нового не печатает. Сборка никогда не останавливается из-за оценки.

Что проверяется

Проверки разбиты на шесть групп. У каждой проверки есть постоянный код, уровень и подсказка, как исправить. Уровень «warning» значит, что читатель скорее всего споткнётся. Уровень «advice» значит, что на страницу стоит взглянуть.

Полный список кодов с причиной и способом исправления — на странице «Ошибки качества документации».

Слова считаются в тексте страницы без блоков кода, живых примеров и кнопок. Латиница считается только для языков с другой письменностью: русского, украинского, китайского и других. Словарь сайта — страница с именем glossary.md, глоссарий.md или словарь.md, либо адрес из настройки quality.glossary. Термином считается слово латиницей со строчной буквы, которое встречается в тексте страницы хотя бы дважды. Имена вроде Docara и сокращения вроде JSON терминами не считаются.

Страницы с noindex в оценку не входят: сайт сам скрывает их от поиска.

Как считается оценка

Формула простая и одна для всех сайтов:

1. Каждая группа страницы начинается со 100 баллов. Невыполненная проверка уровня «warning» снимает 25 баллов, уровня «advice» — 10. Одна проверка снимает баллы один раз, сколько бы раз нарушение ни встретилось на странице. Ниже 0 группа не опускается.
2. Оценка страницы — среднее по группам с весами: полнота 25, актуальность 10, находимость 20, читаемость 15, доступность 15, ссылки 15. Если группа не применяется, например актуальность без отслеживания, она не учитывается, а остальные веса сохраняют пропорции.
3. Оценка группы на сайте и оценка сайта — простое среднее по страницам.

Пример: на странице нет описания (completeness, warning) и неясна тема (findability, advice). Полнота получает 75, находимость 90, остальные группы 100. Без отслеживания документации сумма весов 90, поэтому оценка страницы — (25 × 75 + 20 × 90 + 15 × 100 × 3) / 90 ≈ 91.

Страница «требует внимания», если у неё есть хотя бы одна проверка уровня «warning».

Что исправить в первую очередь

Для каждого найденного нарушения отчёт считает, на сколько баллов вырастет оценка сайта, если исправить только его. Список «Fix first» упорядочен по этому числу. При равенстве выше стоят проверки уровня «warning», затем страницы, на которые ссылается больше других страниц.

Ниже в выводе — «Biggest gains by check»: сколько баллов даст исправление одной проверки на всех страницах сразу. С этого списка удобно начинать большую уборку.

Строгий режим для CI

По умолчанию отчёт только советует. Чтобы он останавливал проверку в CI, задайте нижнюю границу оценки:

php vendor/bin/docara qa report --env=production --min-score=80

Или один раз в docara.authoring.json:

{
  "schema": "docara.authoring.v1",
  "quality": {
    "min_score": 80,
    "glossary": "/ru/reference/glossary/",
    "exclude": ["examples/**"]
  }
}

Смысловая проверка

Программа не может узнать, верно ли написана страница. Поэтому docara qa review-packet готовит пакет вопросов для человека или ИИ-помощника:

php vendor/bin/docara qa review-packet /ru/start/quick-start/ --env=production
php vendor/bin/docara qa review-packet --env=production

С адресом пакет собирается для одной страницы, без адреса — для всего сайта. Пакет записывается в build_production.docara/review-packets/ в двух видах: JSON для программ и Markdown для чтения. В нём есть:

• четыре вопроса к каждой странице: всё ли верно по источникам, понятно ли читателю, решает ли страница задачу, работают ли примеры;
• вопросы профиля страницы, например «Названы ли все условия до первого шага?» для инструкции;
• текст страницы, её профиль, читатели из audiences и отслеживаемые источники;
• нарушения из последнего qa report;
• формат ответа: вопрос, вердикт (pass, fail или unsure), цитата и исправление.

Файл AGENTS.md, который создаёт docara init, просит ИИ-помощника запускать qa report и qa review-packet для каждой изменённой страницы. Те же действия доступны через MCP: инструменты docara_qa_report и docara_qa_review_packet.

Чего отчёт не проверяет

• Внешние ссылки: проверка работает без интернета.
• Правильность фактов и примеров: это вопросы пакета смысловой проверки.
• Оформление и вёрстку: для этого есть браузерная проверка docara qa smart, region и layout (см. команды CLI).

См. также

• Профили страниц — части, которых требует тип страницы
• Актуальность документации — источник для группы «актуальность»
• Ошибки качества документации — все коды проверок
• Команды CLI — параметры qa report и qa review-packet
• Проверка сборки