Объяснение для любой аудитории — Примеры

Пример 1 — Одно изменение, три решения

Платёжный вызов теперь повторяется дважды при тайм-ауте. Три человека действуют по этому по-разному: инженер его сопровождает, продакт-менеджер решает, что говорить клиентам, агент поддержки отвечает по телефону. Напишите объяснение для каждого, до 120 слов.

Изменение  платёжный вызов с тайм-аутом повторяется дважды, повторно
           используя тот же ключ идемпотентности, прежде чем сообщить о сбое
Читатели  инженер, продакт-менеджер, агент поддержки

Решение

Инженерам  Вызов повторяется дважды при тайм-ауте с тем же ключом, так что
           провайдер по-прежнему видит одно списание; медленный случай просто
           ждёт два окна отката, прежде чем упасть. Это приемлемо.
Продукту   До клиента доходит меньше неудачных платежей, а самый медленный
           случай занимает на несколько секунд больше. В ценах ничего не
           меняется.
Поддержке  Если платёж идёт дольше, вот почему. С клиента списывают один
           раз; называйте тот номер обращения, который у вас уже есть.

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

Пример 2 — Спросите о следующем шаге

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

Вы:      ...теперь чтения идут сначала в кэш, а мы инвалидируем его при
         каждой записи. Всё понятно?
Коллега: ага, ясно.

Решение

Вы:      ...теперь чтения идут сначала в кэш, а мы инвалидируем его при
         каждой записи. Если завтра кэш откажет на десять минут, что вы
         ожидаете увидеть и что проверите первым?
Коллега: Чтения упадут назад в базу, значит, нагрузка на базу подскочит.
         Я бы проверил это до самого кэша.

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