Правила написания Release Notes

Release Notes – это документ, описывающий изменения между выпускаемой и предыдущей версиями программного продукта. Адресатом данного документа в первую очередь являются технические специалисты клиента, которые занимаются обслуживанием продукта, интеграторы и команды внедрения. Поэтому документ в первую очередь должен содержать полезную техническую информацию, а не маркетинговые лозунги.

Состав документа

В некоторых конторах в качестве Release notes наружу выдают маркетинговый булшит, а реальное техническое содержание оставляют только для внутреннего читателя. Это косвенно указывает на то, что в продукте много проблем, а производитель ПО вместо их исправления скрывает их. В обратной ситуации, когда принята политика открытости перед пользователем, и его честно информируют о всех косяках в софте, то пользователь будет более лоялен к производителю ПО. В качестве дополнительного бонуса прозрачность мотивирует делать качественные продукты. Стыдно ведь публично писать о своей криворукости.

Сам документ состоит из следующих разделов:

Краткое описание продукта

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

Что нового

Изменение функциональности относительно прошлой версии. Перечисление основных изменений с их кратким описанием. Цель раздела — объяснить пользователю зачем ему тратить своё время и переходить на новую версию.

Исправленные ошибки

Список исправленных ошибок относительно предыдущей версии. Как и предыдущий раздел, этот тоже стимулирует пользователя на апгрейд. Обязательно описать исправленные проблемы, на которые жаловались клиенты и которые были заявлены как known issues в прошлых версиях. Крайне желательно описать те серьезные проблемы, с которыми пользователь мог столкнуться в прошлых версиях, но жалоб на них не поступало. Отсутствие жалоб вовсе не означает, что с ними никто сталкивался. Возможно люди мучились, но у них не хватило сил пробиться через поддержку.

Включать в этот список все содержимое баг трекера не нужно:

• Если баг был сделан, найден и исправлен в процессе разработки текущей версии, то пользователь его видеть не мог, а значит и писать о нем смысла нет.
• Если баг был в прошлой версии, но пользователь его с ним не мог столкнуться. Например, проблема была прикрыта заплаткой в стиле «программа падает при вводе имени пользователя длинной более 10 символов, поэтому мы сделали ограничение на ввод в 9 символов».

Удобно указывать ID проблемы, для удобства истории ошибки.

Список известных проблем или known issues

Если у вас нет known issues – значит никто не тестировал продукт.

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

• ID по которому дальше можно отслеживать его судьбу.
• Workaround. Что делать пользователю, если он встретился с данной проблемой? Если workaround’а нет для критичного бага, значит продукт содержит критическую проблему и не готов к релизу.

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

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

Технические ограничения

Любое ПО имеет технические ограничения. Ваш сервер позволяет работать одновременно 10 пользователям? В базу можно сделать только 10000 записей? UI рассчитан только на Full HD? Напишите об этом.

Системные требования

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

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

Особенности обновления с прошлой версии.

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

Кто пишет документ

Документ должен писать технический писатель, как обладатель грамотного письма. А вот информацию для документа: системные требования, описания workaround’ов, исправленные баги и т.п., должны готовить технические специалисты, руководитель разработки, product manager. Если повесить все на человека, у которого основной навык знание языка, то получиться плохо.

Все новости сайта в телеграм канале: @CTO_in_Action