Привет, Хабр! Меня зовут Иван Арискин, я занимаюсь развитием продукта «Единый адрес» в HFLabs. Поскольку компания сравнительно небольшая, иногда приходится самостоятельно писать и редактировать Release Notes (RN). Они же — новости продуктов, или changelog. За одни меня благодарили, за другие — троллили, но я научился смещать баланс в сторону положительных реакций. 

В статье разберу, что и зачем писать в Release Notes и как заинтересовать бизнес техническими обновлениями. Пригодится всем, кто ведет документацию по продукту и хочет, чтобы она приносила реальную пользу. 

Для кого и зачем мы пишем RN?

Когда задают вопрос из подзаголовка, я отправляю мем.

Теперь о том, кому RN могут быть интересны и полезны.

1. Заказчики. Тут просто: они потратили деньги и ждут результат. 

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

3. Коллеги из других команд. Не забываем о популяризации продуктов внутри компании. Делиться новостями нужно для обмена best practices и просто для появления новых тем за обеденным столом.

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

5. Мы сами. Почему важна история, осознал спустя три года работы. Однажды заказчик спросил про старую фичу: «Почему реализовали так? Нам нужно по-другому». Стал искать причину в задаче и в коде, но не нашел. Ответ скрывался в RN: давным-давно своей же рукой я написал, что клиент сам выбрал такое решение из предложенных, оплатил и остался доволен. Конфликт был разрешен.

Есть еще одна категория, которую не включил в список: админы эксплуатации и поддержка. Они имеют дело с продуктом, когда пришло время его обновить, что-то сломалось или нужно помониторить. Зачем грузить новостями человека, если они понадобятся ему через месяц?.. Поэтому для них лучше подготовить инструкцию.

Что еще нужно иметь в виду при подготовке RN? У кого-то достаточно времени на их чтение, а у кого-то — лишь небольшое свободное окошко. Одни хорошо воспринимают текст, а другим нужна картинка. У всех разная степень осведомленности: кто-то знает ваш стек, а у кого-то вообще нет ИТ-образования. Вывод: понимание аудитории влияет на то, как вы будете преподносить информацию. Например, для бизнеса новости нужно писать максимально просто и понятно, чтобы человек даже при беглом просмотре мог ухватить суть. 

Ищем вдохновение

Прикинул аудиторию, но не могу собраться и сесть писать. Не работается, вдохновения нет. Как быть? Мое решение: аппетит приходит во время еды. Начните писать, причем что угодно. Однажды вообще начал болтать сам с собой и на третьей строчке поймал нужный темп. Можно начать с описания любимой книги или пересказа истории из жизни, анекдотов. У каждого — свой подход. Начните делать хоть что-то, чтобы уйти от пустого листа.

О чем пишем

Когда только пришел в компанию, хотел писать обо всем: «Я же работал, нельзя ничего упустить или забыть — мне за это платят деньги». Такой подход не работает, потому что в основном людей интересуют:

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

• Новые фичи. Часто именно они имеют наибольшую ценность для бизнеса. Здорово, если вы пишете о фичах в срок. В таком случае вы всегда можете подтвердить заказчику, что отдали релиз вовремя, и приложить доказательства. 

• Баги. Не обо всех, конечно, стоит писать. Но если у ошибки есть последствия для клиента, то лучше предупредить до того, как он ее найдет. Однажды мы случайно откопали баг: при нагрузке система могла выдать неправильную информацию в адресах. Никто этого не заметил, но мы решили сказать сразу. Реакция была мягкой: «Плохо, но спасибо за предупреждение, примем меры». Баги, не представляющие серьезной угрозы, обычно исправляем без подробного описания. 

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

Что никому не интересно

Если коротко: все остальное. Например:

• Изменения, которые не касаются заказчика. Вы переписали продукт с Java на Go — это круто. Но если производительность не повысилась, контракты сохранились и для заказчика ничего не поменялось, так ли нужно ему об этом знать? Для своей же истории должна быть отдельная документация. Плюс ко всему, переход на другой язык точно будут помнить и знать все — такое сложно забыть. 

• Процессы разработки. Здесь имею в виду митинги, ретро, релизные циклы. Мы делаем для заказчика четыре обновления в год, но внутри выпускаем их раз в месяц. Сделали раз в две недели, поменяли свои процессы, молодцы! Но даже для истории это лишнее. 

• Технические релизы. Бывало ли такое, что вы здорово поработали, но с клиентом поделиться нечем? После нескольких таких релизов провели ретро и решили, что это проблема планирования, а не Release Notes как таковых. 

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

Как доносить суть понятно

Здесь у меня три основные рекомендации.

1. Сразу разделять аудиторию: бизнесу смотреть сюда, разработчикам — сюда. Если человек не тратит время на непонятное и/или ненужное, он счастлив. 

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

3. Придерживаться четкой и понятной структуры. Мы выбрали такую: 

• Контекст,

• Какую проблему решали,

• Как решили,

• Примеры и ограничения.

Вот как выглядят заголовки обновлений для разной аудитории. А дальше я покажу примеры наших RN. 

Пример №1

Суть обновления: в продукте ускорили метод getByGuid.

Даем контекст: упоминаем прошлый релиз, в котором когда-то появился метод. 

Описываем проблему: раньше метод держал небольшую нагрузку. 

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

Ограничения: суть передаем с точной цифрой, предвещая вопросы про ограничения. 

Пример №2

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

Пример №3

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

Пример №4

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

Пример №5

Что делать с разработчиками, которые не любят ходить по ссылкам? Ниже идеальное описание RN для них. Украл у нашего продукта «Подсказки». Хорошо работает наглядный пример, из которого все понятно без лишних объяснений. Здесь видно, какие данные, в каком поле, где используются. 

Как и чем зацепить читателя

Мало написать новость, нужно еще, чтобы человек захотел ее прочитать. С разработчиками, скажем, легко: чем короче описал техническое поле, тем лучше. А большой читатель иногда хорошо реагирует на кликбейты. Я, как человек с юмором, люблю их использовать. Раньше ждал, что после публикации новости сразу будут писать: «Вань, ты красавчик!». 

Но вот с той же новостью про ускорение метода (пример №1) вышло не так. Впервые она была опубликована с заголовком «Ускорили метод в 100 раз», контекста про релиз 24.15 не было (если что, 100 раз — это правда). Решил порадовать коллег в чате, скинул только заголовок. Не учел одного: про сам метод мы говорили очень давно. Тогда его нужно было выкатить поскорее, а оптимизацию решили отложить. Но у клиента несколько вендоров, множество задач. Контекст не вспомнили, шутку не оценили: заявили, что тогда мы работали плохо, а сейчас исправились. И это действительно выглядело именно так. 

Зацепить читателя можно и с помощью оглавления и структуры. Как-то на встрече случился спор по реализованной функциональности. СЕО компании-клиента не был глубоко погружен в продукт, ему требовалось быстро вникнуть в суть. Предложили изучить документацию. Сижу рядом и замечаю, как он переходит к разным новостям продукта и не листает ни один из них. Ему достаточно оглавления. Пробежавшись по всем релизам за год, он смог поддержать разговор. Более того, сам отметил доработку, ставшую причиной разногласий, — сказал, что только что о ней прочитал. К слову, достаточно детальное оглавление пригодится и разработчикам, ведь некоторые считают себя очень важными это просто удобно.

Также цепляет единообразие. Если мы делаем блок для разработчиков, то он должен быть всегда в одном месте, пусть даже пустой. В таких случаях просто пишем «Изменений нет» на соответствующей подстранице. Когда человек не видит нужного раздела, он начинает думать, что нужно прочитать все — вдруг пропустит что-то важное. 

Еще одна рекомендация: писать так, чтобы читатель узнал себя. Бизнес не скажет «это про меня» после новости про оптимизацию индекса Lucene, а простая жизненная история его зацепит. Ниже на скриншот пример с мостом. Это известная конструкция в Питере, под которой регулярно застревают «газели». После публикации со мной связались двое бизнес-потребителей, один из них написал что-то в стиле «Каждый день езжу около этого моста, увидел в ваших новостях и рассмеялся — уже все про него знают». Другой возразил: «Вообще-то этот мост уже закрыли, неактуальная информация». 

Что сделали мы? Добавили блок «Раскрыть», который гласит: «По информации от нашего читателя Василия из Питера, мост уже закрыт».

Следующий RN, который вызвал обсуждение, — с популярным когда-то мемом с домом-«человейником». В нем очень много жильцов, курьеры постоянно не могут найти адресатов. Связали его с новостью: если в доме тысяча квартир, обязательно уточняйте номер, иначе доставка минут на 30 опоздает. Тоже получили реакцию, но совсем неожиданную: «Такая ностальгия, не представляешь. Это был первый дом, в котором купил квартиру. Когда увидел, вспомнил, как гулял в парке рядом». 

В этот же RN с «человейником» в блок с дополнительной информацией добавили отзыв, как глючит Тиндер. Но в целом с юмором как способом привлечения внимания нужно быть осторожным. Если постоянно шутить, можно потерять большой сегмент аудитории  которая обычно приносит деньги. Да, все люди и все хотят периодически расслабиться, но излишняя неформальность в общении отталкивает. Когда каждая новость сопровождается шуткой, создается впечатление, что фичи создаются ради повода поделиться мемом, а не ради выполнения задач. 

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

Как автоматизировали написание RN

Для подготовки используем шаблоны в задачах Jira. Первым новость пишет либо аналитик, либо продакт, то есть я. Но часто человек в начале не до конца понимает, как именно фича будет реализована, поэтому на последнем этапе задачу проверяет тестировщик. Он уточняет нюансы и при необходимости просит дополнить бизнес-потребность. 

Дальше готовый шаблон парсит робот. Перешли на автоматизацию не сразу: были случаи, когда потратили на классную фичу много времени, но кто-то пропустил задачу и забыл ее описать. Такую фичу никто не купит, потому что просто о ней не узнает. 

Завершаем валидацией. Падает задача выверить, что написали: нужно вычитать структуру, исправить, еще раз исправить. Не потому, что плохо пишем, — что-то может меняться в процессе. Иногда реализация фичи отличается от постановки или пример далек от реальности. Однажды в тексте появился адрес «город Сладкий, улица Синабонная». Естественно, в справочниках налоговой его нет, и на финальной вычитке выдуманный адрес мы убрали.

Что работает лучше всего

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

• Структура «что и для кого». Когда стали так писать, уменьшилось число запросов в поддержку: «Слушайте, мне прилетела задача про ваш метод, но не понимаю, как интеграцию написать». Разработчики тоже начали читать, вникать в рассылки. 

• Оглавление как краткое содержание. Убедился в этом на примере с CEO, да и мне самому это удобно. Когда смотрю новости продуктов трехлетней давности, даже не листаю страницу, поскольку из контекста и заголовков могу уловить смысл. 

• Кликбейты, если ими не злоупотреблять. 

• Истории, которые позволяют читателю подумать: «Это про меня!». После них чаще  всего приходят в личку коллеги из бизнеса. Сейчас каждый вендор хочет продать рассказать, какую фичу он сделал, а мы это делаем с теплотой и интересными деталями.  Для читателя профит: вот он работает, читает новости про продукты, но при этом еще и узнает что-то прикольное из жизни.

В комментариях расскажите, как вы пишите RN — думаю, многим будет полезно узнать о разных подходах. 

P. S. Если вам интересна тема адресов и клиентских данных, подписывайтесь на наш телеграм-канал. А еще у нас есть «Лабсовая» — там пишем о жизни и работе в HFLabs.