Обновите документацию после выпуска версии

1. Четыре читателя

Каждому задетому релизом читателю — отдельный текст в отдельном месте.

Одна фича = 2–4 текста. Типичная ошибка — написать release notes и закончить; через два дня приходит «а куда делась кнопка», а у поддержки про релиз нет ничего.

Раздел для поддержки пишется задом наперёд — от жалобы:

Без строки «эскалировать» поддержка либо эскалирует всё, либо ничего.

2. Release notes против changelog

Нужны оба: changelog отвечает «в какой версии появилось» (споры, инциденты), release notes — «стоит ли обновляться». Правило соответствия: каждая строка release notes имеет опору в changelog; строка без опоры — приукрашивание. Обратное неверно — большая часть changelog наружу не идёт.

3. Что человек теперь может, а не что мы поменяли

Формула строки: [кто] теперь [что может] — [почему это лучше прежнего]. Строку без глагола действия читателя не писать.

Багфиксы — через узнавание: пользователь помнит не номер тикета, а «у меня было странно». «Если при выгрузке в Wildberries вы получали ошибку 400 на товарах с длинным названием — исправлено»; «Исправлена валидация поля name (#4821)» — строка changelog. Баги, не дожившие до прода, не описывай: дефект со стейджа в release notes создаёт впечатление, что продукт разваливается.

4. Ломающие изменения — отдельный жанр

Ломающее — после чего рабочая конфигурация клиента перестаёт работать: удалён эндпоинт/поле, изменён тип/формат, ужесточена валидация, изменено поведение по умолчанию, сокращён лимит, отозван токен.

Пять обязательных блоков (нет одного — описание бесполезно):

1. Что именно сломается — конкретное имя: эндпоинт, поле, параметр, экран.
2. Как понять, что вас касается — проверяемый признак: запрос к логам, строка в конфиге, наличие интеграции.
3. Что сделать — пошагово, с примером «до/после».
4. До какого срока — дата, а не «в ближайшее время».
5. Что будет, если не сделать — перестанет работать / начнёт отдавать ошибку / молча переключится.

Миграция без «до/после» бесполезна — работает только парный блок с реальным кодом:

Было:

Стало:

Пояснения — текстом вокруг блока, не комментариями внутри: limit выше 500 молча обрежется; ответ всегда постраничный; конец данных — только отсутствие next_cursor, пустой items признаком не является (интегратор пишет while resp["items"] и теряет хвост на пустой промежуточной странице).

Срок: три даты в одном предложении — когда новое стало доступно, когда старое начнёт предупреждать, когда перестанет работать. Для интеграций российского SMB (1С-обмены, подрядчик, отвечающий раз в неделю) окно меньше месяца — источник инцидентов. Дат не знаешь — спроси; до ответа оставь явную заглушку и назови её в итоге.

5. Документирование API

Минимальный состав описания эндпоинта (каждый пропуск — входящий вопрос в поддержку):

• Метод, путь с версией, назначение одной фразой на языке задачи.
• Авторизация: тип токена и права.
• Параметры: имя, тип, обязательность, значение по умолчанию, границы (максимум, формат даты, длина строки).
• Примеры запроса и успешного ответа целиком, копируемые, с реальными значениями.
• Пустой результат отдельно: пустой список и отсутствие объекта — разные ответы.
• Пагинация: как взять следующую страницу и как понять, что данные кончились.
• Лимиты: сколько запросов, что приходит при превышении, есть ли заголовок ожидания.
• Идемпотентность изменяющих методов: что при повторе.

Ошибки документируются наравне с успехом — раздела почти никогда нет, а пишут в поддержку из-за него:

Ключевая колонка — четвёртая: интегратору нужен класс, а не текст — лечится повтором / изменением запроса / действиями человека. Без класса 403 превращается в бесконечный цикл ретраев. Отдельно опиши, приходит ли ошибка в теле с HTTP 200: часть российских API, включая кабинеты маркетплейсов, отвечает так, и это первое, что читателю нужно знать.

6. Скриншоты

Самый дорогой элемент: устаревает молча, и читатель верит картинке больше, чем тексту.

Оправдан при одном из трёх: шаг не описать словами однозначно («кнопка в правом верхнем углу» — а их три); читатель ищет элемент глазами в чужом интерфейсе (кабинет Ozon, настройки Битрикс24, 1С); надо показать результат. Не оправдан для полей, называемых по подписи; очевидных последовательностей; экрана, который переделают в ближайший квартал.

Снижай стоимость: снимай область, не весь экран; не свети персональные данные, контрагентов, суммы, ИНН, номера договоров (именно на скриншотах их светят чаще всего); веди список «скриншот — экран продукта», иначе зависимые картинки при правке экрана не найти.

7. Обязательные документы

Оферта и реквизиты — пересматривай при изменении состава тарифа, лимитов, условий возврата, порядка расторжения, SLA. Фиксируй дату вступления редакции и сохраняй прежние редакции: спор идёт о действовавшей на дату оплаты. Реквизиты при смене — сразу везде: сайт, оферта, платёжные страницы, письма, чеки.

8. Состав изменений: как собрать и не соврать

История коммитов — сырьё. Собирай через git_ops: диапазон между тегами прошлого и текущего релиза с датами, авторами и файлами (репозитория нет — склонируй в sandbox_bash).

Четыре корзины, каждый коммит ровно в одну:

1. Видно пользователю → release notes.
2. Видно интегратору (сигнатуры, схемы, эндпоинты) → changelog и справочник API.
3. Видно только нам (рефакторинг, тесты, CI, зависимости) → changelog, дальше не идёт.
4. Не выпущено — код за флагом, выключенным в проде.

Ищи и то, чего в списке коммитов не видно: изменённый default, ужесточённая валидация, снятый лимит, переписанный текст письма — дифф прячет их в одну строку, а вопросов они порождают больше крупных фич. Не понял из истории — спроси автора: пробел порождает вопрос, догадка — неверное действие.

9. Чек-лист обновляемых документов

Проходи все пункты; напротив неприменимых — «не затронуто»: молчаливый пропуск неотличим от забытого.

Внешние тексты

• Release notes на сайте, в продукте, в письме
• Уведомление в канале для действующих пользователей (Telegram, рассылка)
• Раздел «Что нового» внутри продукта

Репозиторий

• CHANGELOG.md — все изменения, включая внутренние
• README — версия, требования, установка, быстрый старт
• Примеры кода в репозитории — ломаются молча
• Конфигурация: новые переменные с описанием и значением по умолчанию

API

• Справочник: новые, изменённые, удалённые эндпоинты
• Схема (OpenAPI и т.п.) сгенерирована заново, а не поправлена руками
• Таблица ошибок дополнена; раздел лимитов, если менялись
• Гид по миграции с примерами «до/после»

Пользовательские материалы

• Пошаговые инструкции по затронутым сценариям
• Скриншоты затронутых экранов, прошедшие проверку раздела 6
• Онбординг — новый пользователь release notes не читает
• FAQ: предсказуемые вопросы

Поддержка

• Заметка «симптом → причина → ответ → когда эскалировать»
• Макросы и шаблоны ответов
• Список временно сломанного или ограниченного

Обязательные документы

• Политика обработки ПДн — при новых данных, целях, получателях, сроках

• Оферта — при изменении тарифов, лимитов, возвратов, SLA

• Реквизиты и контакты — при смене

• Дата редакции и сохранённая предыдущая версия

• Архитектурная документация, если менялись контракты между сервисами

10. Ревизия актуальности — раз в квартал, в одном порядке

1. Даты. Каждый документ несёт дату последней проверки; не тронутое больше полугода — в очередь на просмотр.
2. Ссылки. Битые внутренние и внешние; проверяются автоматически через sandbox_bash.
3. Примеры кода. Прогон примеров — единственная объективная проверка расхождения с кодом.
4. Названия элементов интерфейса. Пройди инструкцию руками, сверь подписи кнопок.
5. Числа. Лимиты, сроки, размеры, цены — каждое число обещание; не подтверждённые сегодня помечай датой актуальности.
6. Расхождение с поддержкой. Топ входящих вопросов за квартал — оглавление того, что документация не объясняет.

Признак брошенной документации — ни одного упоминания версии или даты: читатель считает устаревшим весь текст.

11. Документация удалённой функциональности

Страницу удалённой функции не удалять: она проиндексирована, на неё стоят закладки, а 404 оставляет без ответа. Страница остаётся, содержимое заменяется:

Статус «архив», из навигации убрать, по прямой ссылке и в поиске оставить — человек ищет старое название. Пережить удаление обязаны: как называлась, чем заменена, что стало с данными — последнее забывают чаще всего, и оно порождает самые тяжёлые обращения.