Экстренные Release Notes: Под Давлением Реального Времени

Большинство release notes пишутся после готовности кода, спокойно проверяются, и публикуются по расписанию, не имеющему отношения к тому, насколько срочно кому-то нужно их прочитать. Экстренные релизы, патчи безопасности, баги с потерей данных, исправления сбоев, переворачивают все эти условия разом: заметка должна существовать до того, как большинство людей обычно начали бы её писать, почти не получает проверки, и её читает встревоженная, а не спокойная аудитория. Как писать release notes разбирает нормальный процесс; это о том, что меняется, когда не остаётся времени ему следовать.

Что одно должны сделать правильно экстренные release notes, даже если больше ничего?

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

Применимо ли обычное редактирование, когда нет времени его применять?

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

Бывает ли нормально публиковать заметку до того, как вы действительно уверены в причине проблемы?

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

Слишком уверенно, не проверено:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Честно под давлением времени:
"Исправлено: с некоторых клиентов дважды списывалась
оплата за один заказ. Мы остановили новые случаи и
вернули средства пострадавшим аккаунтам в течение
24 часов. Расследуем первопричину."

Должна ли экстренная заметка упоминать причину проблемы, или только то, что она исправлена?

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

Применима ли здесь же проблема принудительных обновлений мобильных приложений?

Тот же принцип, только ещё более сжатый. Release notes для мобильных приложений разбирает принудительные обновления, где заметка должна назвать причину и крайний срок раньше всего остального, потому что читательница уже раздражена отсутствием выбора; экстренная веб-заметка обычно для читательницы опциональна в том смысле, что она выбирает, действовать ли на её основе, но тот же инстинкт «назвать ограничение первым» применим, просто по другой причине: не раздражение, а срочность.

Как избежать того, чтобы экстренная заметка читалась как признание вины, когда не должна?

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

FAQ

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

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

Должна ли экстренная заметка когда-либо полностью пропускаться, позволяя исправлению выйти тихо? Только для проблем, которые ни одна читательница не могла заметить или которых не затрагивала; если есть шанс, что читательница столкнулась с проблемой, заметка — это то, что сообщает ей, что она закончилась, а тишина читается так, будто проблема всё ещё может быть активной.

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

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

По теме на changeloop: Шаблон релиз-нот, Примеры changelog