Релиз-ноты на практике

Внутренние release notes: кому ещё нужно знать, что вышло

5 мин чтения обновлено

Каждая другая статья в этом хабе предполагает, что читатель release note является клиентом. Саппорт, продажи и customer success тоже читают, или пытаются, и большинство узнаёт, что вышло, потому что клиент спрашивает первым. Этот порядок перевёрнут, и он же принят по умолчанию в большинстве компаний, потому что процесс релиза заканчивается в момент выхода заметки для клиентов, и никто не выстроил второй, меньший шаг для людей, которым час спустя нужно отвечать на вопросы о ней.

Что такое внутренняя release note?

Это более короткий документ, написанный для людей, уже глубоко знающих продукт, который говорит им, что изменилось и что с этим делать в их конкретной работе. Агенту саппорта не нужно отполированное оформление, которое использует анонс для клиентов; ему нужно знать, как изменение выглядит в продукте прямо сейчас, каким будет самый вероятный вопрос о нём, и затронуты ли открытые тикеты. Заметка для клиентов продаёт изменение. Внутренняя вооружает кого-то, чтобы с ним справиться.

АудиторияЧто ей нужно знатьГде ей это нужно
СаппортЧто изменилось в интерфейсе, вероятные вопросы, затронутые открытые тикетыТам, где он уже ищет ответы
ПродажиЧто это открывает для сделки, чего оно ещё не делаетТам, где готовятся к звонкам
Customer successЧто сказать существующим клиентам, и кто это просилТам, где планируют контакт
РуководствоЧто вышло относительно обещанного, и когдаКороткая, повторяющаяся сводка, не на каждый релиз

Как выглядит внутренняя release note?

Одна, для небольшого изменения, заполненная:

Внутреннее: экспорт CSV на странице отчётов (выходит в ср, 21 окт)

Кого касается: все тарифы. Кнопку первыми увидят админы.
Что изменилось: у отчётов появилась кнопка «Экспорт CSV» рядом
  с «Печать». Экспорты свыше 10 000 строк приходят письмом.
О чём спросят клиенты: «Куда делся мой экспорт?», когда большой
  отчёт уходит письмом. Ответ: проверьте почту владельца
  аккаунта; ссылка действует 7 дней.
Открытые тикеты, которые это закрывает: SUP-4182, SUP-4190
  (ответить в день выхода).
Пока нет: нет экспорта по расписанию. Не обещайте дату.
Ссылки: тикет ENG-911 / заметка для клиентов: /changelog#csv-export

Каждая строка отвечает на вопрос, который в течение суток после запуска зададут кому-то из поддержки или продаж. Заметка для клиентов об этом же изменении занимает два предложения; разница между ними и есть смысл этой статьи. Шаблон release notes разбирает сторону для клиентов, а changelog vs release notes объясняет, почему у этих двух документов разные читатели.

Почему внутренние команды узнают с опозданием?

Потому что процесс релиза обычно выстроен вокруг одного артефакта (заметки для клиентов или записи в changelog), и предполагается, что всё внутреннее следует из чтения этого единственного документа. Это не так. Агенты саппорта заняты тикетом перед собой, а не листают changelog в поисках контекста, и заметка, написанная для клиента, часто опускает именно операционную деталь, нужную агенту, например какому плану доступна функция или как выглядит сообщение об ошибке при сбое. К моменту, когда клиент спрашивает, агент читает ту же публичную заметку, что клиент только что прочитал, без какого-либо преимущества.

Что должна включать внутренняя release note?

Операционные детали, которые заметка для клиентов намеренно опускает. Каким планам или аккаунтам это доступно. Как выглядит ситуация, когда что-то идёт не так, и что сказать клиенту, который с этим столкнулся. Закрывает ли это какие-то открытые запросы или тикеты, и какие, чтобы агент, работающий над связанным тикетом, знал, что нужно проверить. Кто в команде отвечает, если вопрос выходит за рамки того, что охватывает заметка. Ничто из этого не принадлежит версии для клиентов, написанной для однократного прочтения кем-то за пределами компании; всё это как раз то, что нужно тому, кто отвечает на один и тот же вопрос сорок раз в неделю.

Внутренняя заметка: массовый экспорт CSV (выходит 08.09.2026)

- Доступно только на планах Team и Enterprise. На Free и Pro без
  изменений.
- Частая ошибка: экспорт свыше 50 тысяч строк уходит в таймаут;
  известная проблема, фикс отслеживается отдельно. Сказать
  клиенту фильтровать по диапазону дат.
- Закрывает 14 открытых запросов с меткой `bulk-export`. Шаблон
  ответа в общем документе.
- Ответственный: команда platform, #platform-eng по всему, что
  выходит за рамки этой заметки.

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

Кто её пишет, и когда?

Тот, кто пишет заметку для клиентов, обычно и есть подходящий человек, потому что у него уже есть весь контекст, но это должен быть отдельный, короткий проход, а не попытка заставить один документ обслуживать обе аудитории. Их объединение производит либо заметку для клиентов, перегруженную внутренними деталями, либо внутреннюю заметку, слишком отполированную, чтобы быть действительно полезной, и на практике быстрее написать два коротких документа, чем договариваться об одном документе, обслуживающем две аудитории сразу. Время важнее авторства: внутренняя заметка должна выходить раньше заметки для клиентов, хотя бы на несколько часов, чтобы саппорт никогда не узнавал об изменении из того же места, что и клиент.

Где ей жить?

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

Сколько проверки ей нужно?

Меньше, и это осознанно. Заметка для клиентов представляет компанию публично и заслуживает внимательного прохода редактирования; внутренняя заметка существует, чтобы быть быстрой и конкретной, и удерживать её на том же уровне полировки обычно как раз и заставляет команды вовсе перестать её писать. Быстрая, слегка сыроватая внутренняя заметка, выходящая за час до запуска, бьёт отполированную, приходящую на следующий день, когда первый тикет саппорта уже пришёл в растерянности.

Версии для клиентов и для разработчиков описаны в статье release notes программного обеспечения.

FAQ

Должны ли внутренние release notes проходить тот же процесс утверждения, что и заметки для клиентов? Нет. Более лёгкий, быстрый проход и составляет смысл. Требование той же проверки превращает внутреннюю заметку того же дня в заметку следующей недели, к которой саппорт уже ответил на вопрос без неё.

Кто отвечает за внутренние release notes, если нет выделенной роли внутренних коммуникаций? Тот, кто пишет заметку для клиентов, делает и второй, короткий проход сразу после. Отдельный ответственный не нужен, нужна только привычка не относиться к заметке для клиентов как к единственному артефакту, который производит релиз.

Нужен ли внутренним release notes собственный changelog или архив? Место с поиском лучше хронологического архива, который никто не пролистывает. Если у саппорта уже есть база знаний, заметка принадлежит туда, помеченная функцией, а не в отдельный внутренний changelog, который помогает только тому, кто уже знает дату выхода.

В чём риск пропускать внутренние release notes для маленьких изменений? Маленькие изменения как раз те, по которым саппорт получает вопросы без предупреждения, потому что маленькое изменение редко получает анонс на уровне компании. Размер release note должен масштабироваться с размером изменения; он никогда не должен опускаться до нуля просто потому, что изменение было незначительным.


Технические утверждения в этой статье не проходили независимую проверку. Если здесь что-то не так, сообщите нам, и мы исправим.

По теме на Changeloop: Примеры changelog, Документация для разработчиков

changeloop
Команда, которая делает changelog, замыкающий цикл. Пользователи о чём-то просят, ваша команда это делает, тот, кто просил, узнаёт об этом.