progcode/editorial/QUALITY_STANDARD.md

# Редакционный стандарт качества

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

## До написания

- Выбрать конкретную проблему, наблюдаемый симптом и практический результат для читателя.
- Проверить как минимум два первичных, нормативных или официальных источника. Для исторического API отдельно назвать версионные ограничения.
- Проверить, что каждая ссылка действительно открывается без обхода TLS и авторизации. Историческую документацию, которая может меняться или исчезнуть, закреплять датированным релизом либо неизменяемым commit, а не ссылкой на неподтверждённый «старый» subdomain.
- Собрать один воспроизводимый пример: код, запрос, конфигурацию, замер или диагностическую последовательность.
- Подобрать собственный визуальный материал: схема, диаграмма, скриншот с разрешением на публикацию или иллюстрация. У изображения должны быть осмысленные `alt` и подпись.

## Каркас статьи

- В первых двух абзацах назвать исходную ситуацию и цену ошибки.
- Показать механизм, а не только рецепт: что меняется, кто владеет состоянием, где проходит граница ответственности.
- Дать читателю рабочий пример и объяснить, какие значения в нём проектные.
- Добавить минимум одну таблицу: сравнение вариантов, матрицу симптомов, контракт данных или последовательность проверки.
- Добавить минимум один рисунок или диаграмму, один пример и один проверяемый источник.
- Закончить конкретным порядком действий, ограничениями и тем, что именно следует проверить в своём проекте.

## Объём и плотность

- Основной текст статьи, без HTML-разметки, заголовка, метаданных и списка источников, занимает от **5 000 до 15 000 знаков**.
- Нижняя граница — не повод искусственно растягивать выводы. Если тема проста, глубину создают контекст, контрпример, проверка и решение, а не повтор одной мысли.
- Верхняя граница — повод разбить слишком широкую тему на серию. Одна статья отвечает на один главный вопрос.
- Каждый абзац либо добавляет факт, решение, ограничение или следующий шаг. Вступления «вообще о важности темы» и эмоциональные связки без технического смысла вырезаются.
- В тело статьи не попадает внутренний редакционный процесс: планы выпуска, source cutoff, editorial date, future-only, synthetic hand-off, `productionEffect`, статусы `not-collected`/`not-attempted`, отчёты о траектории автора и описание того, как статья проверялась. Это материал для review-файла, не тема читательской публикации.

## Техническая речь

- Базовый стиль — **прагматичная краткая техническая речь**. Она следует уровню автора в конкретном году: ранний автор объясняет через собственную задачу, поздний — через измеримый компромисс и воспроизводимый процесс.
- Пишем коротко и предметно: **симптом → причина → проверка → действие**. Предпочитаем глаголы и наблюдаемые факты: «запрос вернул 403», «фильтр исключает запись», «метрика выросла на 18%».
- Один абзац — одна мысль; одно предложение не пытается одновременно описать проблему, историю команды и решение.
- Термин используется только там, где он точнее обычного слова. После первого появления даём расшифровку или пример.
- Не используем общие оценки: «в современном мире», «очень важно», «магическая сила», «просто нужно учитывать». Вместо них называем условие, риск или ограничение.
- В серии из трёх статей нельзя растягивать один общий вводный блок на practice, mechanism и field. Краткое определение можно повторить для самостоятельного чтения, но у каждой статьи должны быть свой главный вопрос, пример, таблица или схема, ограничение и следующий шаг.
- Заголовок обещает ровно тот вопрос, на который отвечает текст. Результат не объявляется «универсальным», если он зависит от версии, нагрузки, прав или архитектуры проекта.

## Редактура по принципам «Пиши, сокращай»

Название раздела отсылает к книге Максима Ильяхова и Людмилы Сарычевой, но не заменяет её чтение и не требует копировать авторские формулировки. Для этого корпуса применяем практический набор правил: читателю проще удерживать короткие смысловые блоки, видеть конкретного действующего участника и находить главное в начале текста.

- Начинаем с действия читателя: какой симптом он увидит, что проверит и какое решение сможет принять. Историю автора, план публикации и отчёт о проделанной редактуре в статью не переносим.
- Пишем о системе через действующие лица и операции: «клиент отправляет запрос», «валидатор отклоняет поле», «сборщик публикует артефакт». Отглагольные существительные и безличные конструкции заменяем глаголом, если при этом не теряется технический смысл.
- В каждом абзаце одна функция: факт, механизм, пример, ограничение или действие. Главное утверждение ставим в начало абзаца и таблицы; пояснение и исключение идут следом.
- Убираем слова, которые не меняют решение: вводные оценки, канцелярские связки, тавтологию, усилители и обещания без доказательства. «Осуществить проверку» становится «проверить», «позволяет выявить» — «показывает», если это действительно тот смысл.
- Делим перегруженные предложения. Ориентир — не более 35 слов в обычном предложении; более длинное оставляем только для точного определения, формулы или условия, которое иначе станет двусмысленным. Команды, идентификаторы, JSON и код не переписываем ради длины.
- Каждое обобщение подкрепляем наблюдаемым примером, числом, таблицей, кодом или источником. Если данных нет, называем границу знания прямо и формулируем следующий способ проверки, без фиктивного результата.
- Технический термин сохраняем, когда он точнее бытового слова. При первом появлении даём короткую расшифровку; одинаковый термин не заменяем декоративными синонимами.
- Сокращение не должно убрать механизм, контрпример, ограничение или проверку. Цель редактора — высокая плотность смысла, а не минимальное число знаков.

### Три прохода по длинному тексту

1. **Смысл.** Вынести проблему и цену ошибки в начало, проверить один главный вопрос, убрать рассуждения о личности автора, планах, корреляциях и ходе написания.
2. **Слова и предложения.** Заменить абстрактные связки конкретными действиями, сократить повторения и канцелярит, разделить перегруженные предложения, проверить согласование терминов и субъектов.
3. **Доказательства.** Вернуть только те примеры, таблицы, схемы, числа и ссылки, которые помогают проверить вывод. Сверить код с описанием и убедиться, что после сокращения не исчезли версия, условие применимости и ограничение.

Автоматический аудит подсвечивает мета-лексику, шаблонные обороты и слишком длинные предложения. Финальное решение принимает редактор: техническая формула, API-идентификатор и фрагмент кода могут быть длинными по необходимости, а обычная фраза — только по причине, которую можно объяснить.

## Голос автора

- Для 2017–2018 годов — практичная, тёплая заметка инженера: «давайте разберём», осторожные выводы, внимание к реальной ошибке и следующему шагу.
- Для 2019–2021 годов — инженер развивает T-shape: от PHP и Bitrix к фронтенду, инфраструктуре и данным. Текст всё ещё говорит от первого лица, но уже связывает решение с границами системы.
- Для 2022–2024 годов — системный практик: появляются измерения, надёжность, безопасность, доставка и взаимодействие ролей. Утверждения становятся проверяемее, а выводы — спокойнее.
- Для 2025–2027 годов — наставник и техлид: автор сравнивает варианты, называет стоимость решения, объясняет компромиссы и оставляет команде воспроизводимый способ работы.
- Не подменять опыт общими фразами вроде «важно учитывать» или «магическая сила». Каждое обобщение должно опираться на случай, код, таблицу или источник.
- Не делать вид, что исторический автор уже знает инструменты и практики 2027 года. Поздние материалы могут становиться системнее, но развитие должно быть постепенным.
- Термины и сокращения раскрываются при первом появлении, если они не очевидны из контекста кода.
- Полная временная карта, словарь, переходы навыков и анти-анахронизмы находятся в `editorial/voice/author-trajectory-2017-2027.md`; она обязательна для редакторского прохода.

## Тройное ревью перед публикацией

1. **Факты и техника.** Сверить утверждения с источниками, проверить пример, версионные оговорки, ссылки и отсутствие ложных обещаний.
2. **Редактура и голос.** Проверить постановку проблемы, объём 5–15 тыс. знаков, плотность, прагматичность речи, естественность тона соответствующего года, повторы и ясность переходов. Удалить внутреннюю мета-лексику и проверить, что статья отвечает на технический вопрос читателя, а не описывает автора или редакционный процесс. Для месячной тройки отдельно сравнить статьи между собой: общий контекст не заменяет самостоятельное раскрытие каждого вопроса.
3. **Визуал и выпуск.** Открыть изображения и диаграммы, проверить таблицы на узком экране, доступность `alt`/подписей, JSON, автоматический аудит и production-сборку.

Каждый проход должен оставить конкретную правку или явное обоснование, почему правка не нужна; запись одного `PASS` без списка изменений не считается ревью. Результат каждой ручной проверки фиксируется рядом с партией в `editorial/reviews/`.