| name | doc-quality-review |
| description | Детерминированная рубрика ревью качества уже написанной документации репозитория по 6 ядровым характеристикам IBM-фреймворка «Developing Quality Technical Information» (Hargis, Carey et al.) — task orientation, accuracy, completeness, clarity, organization, retrievability — адаптированным под markdown-доки. Рассчитан на слабую модель (уровня Qwen 37B): ✓/✗-проверки, правило «если ✗ → действие», сводный вердикт и план правок. Применять, когда нужно ОТРЕВЬЮИТЬ существующие README / docs/architecture.md / прочие доки на качество. Не применять для написания доки с нуля — это скилл documentation; характеристики style / concreteness / visual намеренно вне ядра. |
Ревью качества документации — рубрика 6 характеристик
Скилл оценивает уже написанную документацию. На вход — файл(ы) доки и тип
документа. На выход — заполненная рубрика (✓/✗ по каждой проверке), список правок
и сводный вердикт.
Источник рубрики: IBM «Developing Quality Technical Information: A Handbook for
Writers and Editors» (Hargis, Carey и др.). Взято ядро 6 из 9 характеристик,
релевантных для dev-доков; проверки переформулированы под markdown-репозиторий.
Написать или пересобрать доку (не ревью) — скилл documentation.
Найти, куда положить контент, — раздел «Роутер» там же.
0. Как пользоваться
- Определи тип документа и его JTBD-сегмент (см.
documentation, раздел 6).
Не понял сегмент → STOP (раздел 8), спроси оператора.
- Иди по разделам 2–7 по порядку. В каждом — поставь ✓ или ✗ по каждой проверке.
✓ = условие выполнено буквально. Сомнение = ✗ (не натягивай).
- Каждый ✗ → возьми действие из колонки «если ✗ → действие». Запиши в план правок.
- В конце заполни сводную таблицу (раздел 7→итог) и вердикт.
- Не чини сам, если правка меняет смысл или удаляет факт → STOP, спроси.
Шкала вердикта характеристики:
- OK — все проверки ✓.
- Правки — есть ✗, но документ пригоден, чинится точечно.
- Переделать — ✗ больше половины проверок характеристики.
1. Что ревьюим под какой тип
| Тип документа | Какие характеристики применяй |
|---|
README.md | Все 6 (разделы 2–7) |
docs/architecture.md | Task orientation, Accuracy, Completeness, Organization (2,3,4,6) |
| ADR / devlog / прочее | Accuracy, Clarity, Retrievability (3,5,7) |
2. Task orientation (ориентация на задачу)
Документ помогает пользователю сделать его работу, а не описывает функции продукта.
| Проверка | если ✗ → действие |
|---|
Документ написан под конкретный JTBD-сегмент (раздел 6 documentation), а не «для всех» | Определи целевой сегмент, выкинь чужой контент по роутеру |
| Текст с точки зрения пользователя («чтобы запустить — сделай X»), а не системы | Перепиши от лица читателя |
| У каждого блока виден практический смысл (зачем читать) | Добавь одну фразу «зачем» или удали блок |
| Фокус на реальных задачах (запустить, подключить, доработать), а не на перечне функций | Переформулируй функции в задачи |
| Заголовки раскрывают задачу («Запуск», «Подключение»), а не абстрактны («Общее») | Переименуй заголовки в задачи |
| Инструкции разбиты на дискретные шаги, каждый шаг — одно действие | Разбей абзац-инструкцию на нумерованные шаги |
3. Accuracy (точность)
Документ соответствует коду и контракту, ничего устаревшего.
| Проверка | если ✗ → действие |
|---|
Таблица API и pipe соответствуют api-specification/ (эндпоинты, методы) | Синхронизируй с контрактом; нет контракта → STOP |
| Команды запуска реально работают (скопировал — выполнилось) | Исправь команду или пометь TODO в backlog.md |
Факты согласованы между README, architecture.md, ADR (нет противоречий) | Приведи к одному значению; источник истины — контракт/код |
| Ссылки на связанные документы корректны и ведут куда указано | Почини путь (см. раздел 7) |
| Нет упоминаний удалённых модулей/флагов/эндпоинтов | Удали устаревшее |
4. Completeness (полнота)
Покрыто всё, что нужно задаче, и только это.
| Проверка | если ✗ → действие |
|---|
Присутствуют все обязательные блоки типа (для README — проходы A1–A7 documentation) | Добавь недостающий блок |
| Каждый эндпоинт из таблицы API имеет pipe-описание | Допиши недостающие pipe |
| Детали — ровно сколько нужно сегменту, без переусложнения | Срежь лишние детали реализации |
| Нет контента не из этого файла (концепт-уровень, чужой сервис) | Унеси по роутеру (раздел «Роутер» documentation) |
| Информация не повторяется без пользы (один источник правды) | Замени дубль ссылкой на источник |
5. Clarity (ясность)
Однозначно, коротко, термины определены.
| Проверка | если ✗ → действие |
|---|
| Овервью «что это» — одно предложение ≤ 20 слов, не абзац | Сократи до одного предложения |
| Нет двусмысленных местоимений/отсылок («это», «он» без явного антецедента) | Замени местоимение существительным |
| Элементы короткие (предложение ≤ ~25 слов, пункт списка ≤ ~12 слов) | Разбей длинное на части |
| Каждый новый термин определён при первом употреблении | Дай определение или ссылку на глоссарий |
| Один термин для одного понятия по всему документу (нет синонимов-путаницы) | Унифицируй терминологию |
| Похожая информация подана единообразно (одинаковые таблицы/шаблоны) | Приведи к одному формату |
6. Organization (организация)
Контент в правильном файле, в правильном порядке, видно как части складываются.
| Проверка | если ✗ → действие |
|---|
| Каждый кусок — в своём файле по роутеру (один тип контента = одно место) | Перенеси кусок в нужный файл |
| Порядок блоков — по порядку использования (что это → запуск → вглубь) | Переставь блоки в порядок «лестницы» |
| Контекст/обоснования отделены от инструкций (ADR отдельно от шагов запуска) | Вынеси обоснования в docs/adr/ |
| Иерархия заголовков ровная: у ветки разумное число подпунктов (не 1 и не 15) | Сгруппируй или подними подпункты |
| Главное выделено, второстепенное подчинено (не всё одним уровнем) | Перестрой уровни заголовков |
| Видно, как части системы складываются вместе (дерево модулей / лестница ссылок) | Добавь дерево модулей или лестницу контекста |
7. Retrievability (находимость)
Читатель быстро находит и переходит куда нужно; ссылки рабочие и осмысленные.
| Проверка | если ✗ → действие |
|---|
| Все ссылки резолвятся (нет битых/висячих путей к несуществующим файлам) | Почини путь или создай целевой файл; иначе убери ссылку |
| Текст ссылки описателен («docs/architecture.md — устройство», не «здесь»/«click») | Перепиши якорь ссылки в осмысленный |
| В первых строках README есть указатель на concept-репо | Добавь строку-указатель (см. documentation, роутер) |
| Есть лестница вглубь (ссылки на component-tests → architecture → adr → contributing) | Добавь недостающие ссылки лестницы |
| Заголовки навигабельны: по ним одним понятно содержание (мысленное оглавление) | Переименуй неинформативные заголовки |
| Целевой раздел ссылки легко найти на той стороне (ссылка ведёт в нужное место, не «в начало большого файла») | Уточни якорь/раздел назначения |
8. STOP-правила
Остановись и спроси оператора, если:
- Не определяется JTBD-сегмент документа.
- Правка требует удалить или переписать содержательный факт — спроси, куда его деть.
- Нет контракта
api-specification/, а Accuracy требует сверки API.
- Ссылка висячая, но непонятно — целевой файл должен появиться позже или ссылку убрать.
- Документ написан человеком и правка масштабная (переделка) — подтверди before.
9. Итог ревью
Заполни сводку. Для каждой применённой характеристики — вердикт из раздела 0.
Документ: <путь> Сегмент: <1/2/3/4>
| Характеристика | ✓ / всего | Вердикт |
| Task orientation | _ / 6 | OK/Правки/… |
| Accuracy | _ / 5 | |
| Completeness | _ / 5 | |
| Clarity | _ / 6 | |
| Organization | _ / 6 | |
| Retrievability | _ / 6 | |
Сводный вердикт: <годен как есть / точечные правки / переделать>
План правок:
1. <файл:место> — <что сделать> (из «если ✗ → действие»)
2. ...
Сводный вердикт:
- Годен как есть — все характеристики OK.
- Точечные правки — есть «Правки», нет «Переделать».
- Переделать — хотя бы одна характеристика «Переделать» → верни в скилл
documentation.
