Ведь если история изменений пишется, значит, это кому-нибудь нужно!
Привет! Я Арина, работаю техническим писателем в IT больше 7 лет и люблю заниматься текстами, которые, кажется, мало кому нравятся: текстами об изменениях в продукте (Историями изменений, What's New, Release Notes и подобными ченджлогами). И я твёрдо убеждена, что такие тексты, во-первых, читают, а во-вторых, через них можно и нужно нести реальную пользу. Эта статья о том, как писать для тех, кто вас реально читает.
Заметка перед началом
Здесь я буду писать в основном о документации для B2B: для тех, кто использует ваши продукты (API, SDK, инструменты аналитики и т.д.) для разработки своих решений.
Да кто вообще читает об изменениях?
Ваша самая дорогая аудитория: постоянные пользователи. Разработка в B2B часто связана с работой с несколькими крупными заказчиками, которые действительно заинтересованы в эффективности вашего продукта, потому что от них зависит их собственный успех. И в очередном обновлении клиенты, использующие ваш продукт в своём бизнесе, ожидают, что:
Починили тот самый бесячий баг, который застопорил их процессы в прошлом месяце. И не дал им заработать много денег.
Вышла новая фича, которую они ждали (может быть, даже просили) и которую применят у себя, чтобы сделать своё решение ещё круче. И смогут заработать много денег.
Вышло что-то новое и интересное, о чем они не знали раньше, но что заставит их подумать о новых возможностях, которые можно внедрить в своё решение. И, возможно, заработать много денег.
Конечно, здесь стоит допустить, что для вашей основной аудитории может быть важно «чтобы просто всё стабильно работало» — и это ок, если такова основная метрика успеха вашего продукта и если действительно никаких принципиально новых возможностей не появляется.
Кто должен за это отвечать?
Ответственность за описание изменений — вопрос спорный. Где-то этим занимаются аналитики, где-то продакты, где-то тестировщики или маркетологи. Лично мне, как техническому писателю, отвечать за такие тексты нравится и кажется логичным по нескольким причинам:
Это не даёт шанса не быть в курсе событий.
А если на этапе описания изменений нашли что-то, что прошло мимо команды технических писателей — это отличный повод сходить
побубнитьобсудить процессы.Это здорово развивает навык техписателя «быть мостом между разработчиками и клиентами».
Моя команда пишет об изменениях для пользователей на основе заметок от разработчиков, и вот тут каждое предложение заставляет мозг напрячься и подумать, как превратить внутренний сленг в понятное для пользователя предложение (об этом расскажу подробнее дальше).
Часть описываемых изменений обычно находит отражение в других документах, которыми точно владеет техписатель (руководства пользователя и т.д.), и выстроить связи между всеми документами может именно он.
Если описаниями изменений занимается другой человек (например, аналитик), постарайтесь поучаствовать хотя бы на этапе вычитки. Почему — см. выше.
Но вот сбор этих изменений — это совсем иной процесс и явно входит в рабочие обязанности менеджеров. А техническому писателю стоит поучаствовать в формировании этого процесса как заинтересованному лицу.
Как писать, чтобы читали?
Сразу спойлер: «заманить» нового читателя в историю изменений просто хорошими текстами вряд ли получится. Но можно сделать их полезными и приятными для тех, кому действительно хочется узнать об изменениях.
Представьте: команда разработки прислала вам список изменений, которые войдут в ближайший релиз, с подробными (и не очень) комментариями. Например, формулировка такая:
Добавили новую переменную
LOCALE, которая позволяет задать язык приложения по умолчанию.
Чтобы «обработать» эту формулировку и сделать её максимально полезной для пользователя, зададим себе и команде следующие вопросы:
Можно ли об этом изменении писать публично или для читателей конкретной истории изменений?
Лучше лишний раз переспросить (или подкрутить процесс сбора), чем случайно опубликовать что-то, не предназначенное для глаз пользователей.
Все ли детали относятся непосредственно к читателю истории изменений?
В нашем примере: если для читателя (конечного пользователя) язык приложения будет меняться через кнопку в интерфейсе, а самой переменной он нигде не увидит, то не стоит его лишний раз путать.
Какая новая возможность появилась именно для читателя?
Этот вопрос помогает превратить отчёт от разработки в заботу о пользователе и его интересах. В нашем примере стоит вынести вперед новость о том, что теперь можно менять язык приложения, а как именно — отодвинуть.
Теперь вы можете задавать язык приложения по умолчанию через новую переменную
LOCALE.Достаточно ли пользователю информации, чтобы воспользоваться новой возможностью?
В истории изменений сложно (да и не нужно) описывать все детали и давать инструкции по новым возможностям. Но нельзя ставить пользователя в тупик: дайте подсказку, где посмотреть детали, куда обратиться за доступом, к какой уже известной функциональности относится это изменение. Иначе после прочтения у читателя может возникнуть логичный вопрос: «И что?».
Добавим подсказку к нашему примеру:
Теперь вы можете задавать язык приложения по умолчанию через новую переменную
LOCALE. Список доступных значений переменной см. [по ссылке].Поймёт ли нас читатель остальной документации по продукту?
Следим за словами: легко пропустить использование внутреннего жаргонизма вместо привычного, уже устоявшегося в документации термина.
Не заслоняет ли форма смысл?
Есть распространённая рекомендация начинать описание изменений с глагола или причастия: добавлена возможность, исправлена ошибка, улучшена работа. И это хорошая практика, пока она не ставит палки в колёса читающему. Представьте, как бы вы сами вслух сказали об изменении, и сравните с конструкцией, где впереди стоит причастие. Если и то, и другое ложится хорошо и понятно — прекрасно, придерживайтесь стандартной структуры.
Пример двух формулировок, которые в обоих вариантах звучат неплохо:
Добавлен учёт сезонных ограничений при поиске маршрута на общественном транспорте.
При поиске маршрута на общественном транспорте теперь учитываются сезонные ограничения.
Но иногда как ни крути формулировку, не получается красиво и понятно рассказать об изменении, не отойдя от привычной схемы:
Папки с фотографиями заменены на альбомы с встроенным слайд-шоу.
Заменены папки...? Изменена форма папок...? Добавлены альбомы вместо папок...?
Заключение
Хорошая история изменений — это ещё один способ позаботиться о пользователе вашего продукта. А пользователи чувствуют, когда вам не всё равно ;)
