doc-quality-review

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. Как пользоваться

1. Определи тип документа и его JTBD-сегмент (см. documentation, раздел 6). Не понял сегмент → STOP (раздел 8), спроси оператора.
2. Иди по разделам 2–7 по порядку. В каждом — поставь ✓ или ✗ по каждой проверке. ✓ = условие выполнено буквально. Сомнение = ✗ (не натягивай).
3. Каждый ✗ → возьми действие из колонки «если ✗ → действие». Запиши в план правок.
4. В конце заполни сводную таблицу (раздел 7→итог) и вердикт.
5. Не чини сам, если правка меняет смысл или удаляет факт → 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.