Ведь если история изменений пишется, значит, это кому-нибудь нужно!

Привет! Я Арина, работаю техническим писателем в IT больше 7 лет и люблю заниматься текстами, которые, кажется, мало кому нравятся: текстами об изменениях в продукте (Историями изменений, What's New, Release Notes и подобными ченджлогами). И я твёрдо убеждена, что такие тексты, во-первых, читают, а во-вторых, через них можно и нужно нести реальную пользу. Эта статья о том, как писать для тех, кто вас реально читает.

Заметка перед началом

Здесь я буду писать в основном о документации для B2B: для тех, кто использует ваши продукты (API, SDK, инструменты аналитики и т.д.) для разработки своих решений.

Да кто вообще читает об изменениях?

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

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

• Вышла новая фича, которую они ждали (может быть, даже просили) и которую применят у себя, чтобы сделать своё решение ещё круче. И смогут заработать много денег.

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

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

Кто должен за это отвечать?

Ответственность за описание изменений — вопрос спорный. Где-то этим занимаются аналитики, где-то продакты, где-то тестировщики или маркетологи. Лично мне, как техническому писателю, отвечать за такие тексты нравится и кажется логичным по нескольким причинам:

• Это не даёт шанса не быть в курсе событий.

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

• Это здорово развивает навык техписателя «быть мостом между разработчиками и клиентами».‎

  Моя команда пишет об изменениях для пользователей на основе заметок от разработчиков, и вот тут каждое предложение заставляет мозг напрячься и подумать, как превратить внутренний сленг в понятное для пользователя предложение (об этом расскажу подробнее дальше).

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

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

Но вот сбор этих изменений — это совсем иной процесс и явно входит в рабочие обязанности менеджеров. А техническому писателю стоит поучаствовать в формировании этого процесса как заинтересованному лицу.

Как писать, чтобы читали?

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

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

Добавили новую переменную LOCALE, которая позволяет задать язык приложения по умолчанию.

Чтобы «обработать» эту формулировку и сделать её максимально полезной для пользователя, зададим себе и команде следующие вопросы:

• Можно ли об этом изменении писать публично или для читателей конкретной истории изменений?

  Лучше лишний раз переспросить (или подкрутить процесс сбора), чем случайно опубликовать что-то, не предназначенное для глаз пользователей.

• Все ли детали относятся непосредственно к читателю истории изменений?

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

• Какая новая возможность появилась именно для читателя?

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

  Теперь вы можете задавать язык приложения по умолчанию через новую переменную LOCALE.

• Достаточно ли пользователю информации, чтобы воспользоваться новой возможностью?

  В истории изменений сложно (да и не нужно) описывать все детали и давать инструкции по новым возможностям. Но нельзя ставить пользователя в тупик: дайте подсказку, где посмотреть детали, куда обратиться за доступом, к какой уже известной функциональности относится это изменение. Иначе после прочтения у читателя может возникнуть логичный вопрос: «И что?».

  Добавим подсказку к нашему примеру:

  Теперь вы можете задавать язык приложения по умолчанию через новую переменную LOCALE. Список доступных значений переменной см. [по ссылке].

• Поймёт ли нас читатель остальной документации по продукту?

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

• Не заслоняет ли форма смысл?

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

  Пример двух формулировок, которые в обоих вариантах звучат неплохо:

  Добавлен учёт сезонных ограничений при поиске маршрута на общественном транспорте.

  При поиске маршрута на общественном транспорте теперь учитываются сезонные ограничения.

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

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

  Заменены папки...? Изменена форма папок...? Добавлены альбомы вместо папок...?

Заключение

Хорошая история изменений — это ещё один способ позаботиться о пользователе вашего продукта. А пользователи чувствуют, когда вам не всё равно ;)