Структурный review технической статьи
Проверяй, помогает ли статья выполнить обещанную читателю задачу и поддержаны ли её существенные выводы. Количество иллюстраций, длины абзацев и отношение тезисов к примерам сами по себе не измеряют достоверность.
Вход и границы
Используй существующий запрос, черновик, первичные материалы и правила площадки. Не запускай все смежные writing-навыки подряд: подключай только нужный для конкретного оставшегося дефекта. Запрос «проверить» означает review без правок; «исправить/подготовить/опубликовать» включает соответствующую работу.
1. Задача читателя и жанр
| Жанр | Что должно быть понятно |
|---|---|
| Reference | где найти факт, условие, контракт или действие |
| Tutorial | исходные условия, шаги, результат и проверка |
| Analysis | данные, метод, вывод и границы переноса |
| Story | что действительно произошло и чему научился автор |
| Opinion | что является позицией автора и чем она обоснована |
Выбери основной жанр из запроса и назначения текста, не из привычки. Смешение допустимо, если читатель понимает переход. Не превращай справочник в историю или отчёт в рекламный материал, чтобы он выглядел «живее».
Для каждой секции назови её пользу читателю. Определение, таблица или короткий блок могут быть достаточны; им не требуется выдуманная личная история.
2. Тезис и соответствующее доказательство
Различай факт, предположение, вывод из данных, проектную рекомендацию и гипотетический пример. Подбирай основание по типу утверждения.
| Утверждение | Подходящее основание | Чего недостаточно |
|---|---|---|
| API ведёт себя так | текущая документация нужной версии или реальный probe | похожий пример другой версии |
| изменение исправляет дефект | failing case и свежая проверка изменённого пути | компиляция или объяснение автора |
| результат получен в продукте | соответствующий runtime/result receipt | source review, макет, синтетический тест |
| метод быстрее | сопоставимый baseline, условия и измерение | субъективное впечатление |
| подход рекомендуется | явно названные условия и инженерное обоснование | представление мнения как доказанного закона |
| событие произошло с автором | реально предоставленное свидетельство | правдоподобный придуманный рассказ |
Источник должен подтверждать конкретное утверждение, а не просто быть о той же теме. Код иллюстрирует механизм; его наличие не доказывает правильность или запуск. Гипотетический пример помогает объяснить, но не заменяет наблюдение.
Не требуй фиксированного отношения 2:1, трёх чисел или отдельного примера под каждым определением. При нехватке основания сузь тезис, проверь источник в рамках исследовательской задачи либо обозначь неизвестное. Не заполняй пробел вымышленной метрикой, цитатой, личным опытом или статусом PASS.
3. Ограничения и статус готовности
Технический текст должен ясно сообщать существенные ограничения своего вывода: версию, область применимости, неподтверждённый runtime, допущения и компромиссы. Для статьи о собственном инструменте/подходе удобен отдельный блок ограничений. В коротком справочнике условия можно поставить непосредственно рядом с правилом.
Не придумывай поломку «после 10K записей» или ложную скромность ради раздела. Не прячь известную зависимость только потому, что она внешняя. Назови её влияние. Различай «проверено в исходнике», «прошёл fixture», «установлено» и «работает в нужном сценарии». Сильнее имеющегося доказательства статус не становится.
4. Организация без искусственных квот
- Порядок секций следует задаче: необходимый контекст перед зависимым выводом.
- Повтор полезен для точного термина или параллельного сравнения; повтор того же вывода без новой информации обычно можно убрать.
- Разгружай середину, если читатель теряет ход мысли, а не потому что превышен произвольный процент тезисов.
- Не максимизируй дисперсию длин абзацев. Один цельный абзац может быть лучше нескольких искусственно разрубленных.
- Добавляй таблицу/схему только когда она заметно проясняет сравнение, связи, иерархию или последовательность. Не дублируй уже ясную прозу картинкой.
- Длинные самостоятельные примеры выноси только если это нужно структуре площадки; не плодить отдельный файл ради формального прохождения проверки.
5. Закрытие редакторского этапа
Для каждого существенного замечания назови место, нарушенную задачу читателя или неподдержанный тезис и конкретную правку. При разрешённой редактуре внеси её, затем перепроверь затронутый смысл и ссылки. Независимый reviewer нужен для рискованных/спорных утверждений по принятому процессу, не бесконечно.
Если критерии статьи выполнены, редакторский этап закончен. Продолжай оставшуюся запрошенную публикацию; файл с замечаниями или успешное review её не заменяют. Не заявляй видимость статьи по одному Git-коммиту.
Gotchas
- Пример вместо доказательства: убедительный вымысел не подтверждает факт.
- Арифметический стиль-гейт: отношения и квоты заставляют раздувать уже достаточный текст. Проверяй понимание и смысл.
- Смена жанра: личная история не обязательна для reference.
- Переоценка готовности: source/fixture/install/runtime — разные утверждения.
- Review self-feed: повтор без изменённого риска тормозит реальную публикацию.
Troubleshooting
| Симптом | Причина для проверки | Действие |
|---|---|---|
| много тезисов, мало оснований | утверждения сильнее источников | проверить, сузить или обозначить гипотезу |
| читатель теряется в середине | пропущен переход или предпосылка | переставить/уточнить нужный блок |
| появились новые числа и истории | пример принят за свидетельство | удалить вымысел, восстановить фактуру |
| оформление меняется по кругу | критерий подменён квотой | проверить задачу читателя и завершить этап |
| статья готова, но не опубликована | review принят за terminal outcome | выполнить разрешённый путь публикации и проверить видимость |
Основание и сопровождение
Локальное основание: наблюдаемый конфликт прежних количественных квот и обязательной сюжетности с фактически обоснованным техническим справочником. Это не измеренное доказательство ускорения разработки.
Проверено 2026-09-06. Ответственный — существующие сопровождающие writing-навыков. При изменении контракта сохрани baseline, проверь случаи «reference без истории», «неподтверждённая метрика», «fixture не runtime» и передай diff независимому reviewer. Установка — из канонического Git; откат — предыдущая ревизия и бэкап. Не повторяй исследование без изменения источника или наблюдаемой регрессии.
Developer documentation voice and tone (обновлено 2026-05-27, проверено 2026-09-06) поддерживает приоритет полезной, ясной информации для аудитории. Числовых норм thesis/proof или дисперсии абзацев этот источник не устанавливает.
