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

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

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

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

Что нужно поддержке, чего нет больше нигде

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

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

2. Release notes против changelog

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

Нужны оба: changelog отвечает «в какой версии это появилось» и нужен в спорах и при разборе инцидентов, release notes отвечают «стоит ли обновляться» и читаются один раз.

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

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

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

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

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

Пять обязательных блоков

Нет хоть одного — описание бесполезно.

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

Миграция без «до/после» бесполезна

«Замените getOrders на orders.list с учётом новой пагинации» не помогает: читатель не знает, что такое «новая пагинация», и не понимает, куда девать параметры. Работает только парный блок с реальным кодом.

Было:

Стало:

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

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

Минимальный состав описания эндпоинта

Каждый пропущенный пункт превращается во входящий вопрос в поддержку.

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

Ошибки документируются наравне с успехом

Раздела ошибок почти никогда нет — и именно из-за него пишут в поддержку.

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

Отдельно опиши, приходит ли ошибка в теле с HTTP 200: часть российских API, включая кабинеты маркетплейсов, отвечает 200 с полем ошибки внутри, и это первое, что читателю нужно знать.

6. Скриншоты и стоимость владения

Скриншот — самый дорогой элемент документации: он устаревает молча. Устаревший текст противоречит сам себе, и это замечают; картинка просто показывает интерфейс, которого нет, и читатель верит ей больше, чем тексту.

Когда скриншот оправдан

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

Не оправдан для полей формы, называемых по подписи; очевидных последовательностей; экрана, который планируют переделывать в ближайшем квартале.

Как снизить стоимость

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

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

Обновляются потому, что релиз изменил фактическое положение дел. Правят их реже, но пропуск здесь дороже всех остальных.

Оферта и реквизиты

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

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

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

Четыре корзины

Каждый коммит попадает ровно в одну:

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

Изменения, которых нет в списке коммитов

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

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

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

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

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

Репозиторий

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

API

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

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

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

Поддержка

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

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

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

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

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

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

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

10. Проверка актуальности как повторяемая процедура

Документация гниёт незаметно. Раз в квартал прогоняй ревизию в одном порядке — тогда это работа на часы, а не на неделю.

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

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

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

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