How to Write Better with The Why, What, How Framework

eugeneyan

Начать здесь Тексты Выступления Прототипирование О себе

Как писать лучше с помощью фреймворка «Почему, Что, Как»

[ тексты инженерия продуктивность 🩷 🔥 ] · чтение 10 мин

Вот история из ранних дней Amazon Web Services: прежде чем написать хоть строчку кода, инженеры потратили 18 месяцев на размышления и написание документов о том, как лучше всего обслужить клиента. Amazon считает, что это и есть самый быстрый способ работать — глубоко продумать, что нужно клиенту, прежде чем строго и выверенно реализовывать эту идею.

Точно так же и я как data scientist: хотя я решаю задачи через код, значительная часть работы происходит до написания кода. Эта работа принимает форму размышлений и/через написание документов. Особенно это так в Amazon, который знаменит своей культурой письма.

Этот пост (и следующий) отвечают на вопрос, набравший больше всего голосов в опросе тем:

Как писать design-документы для проектов в data science / машинном обучении?

Начну с трёх типов документов, которые я писал: one-pager'ы, design-документы и after-action review. Затем раскрою фреймворк, который использую для структурирования большинства своих текстов, включая этот пост. В следующем посте мы обсудим design docs.

One-pager'ы, design docs, after-action review

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

Три типа документов, которые пишутся в ходе проекта

One-pager'ы: использую их, чтобы достичь согласованности со стейкхолдерами из бизнеса/продукта. Также применяю как фоновые памятки для квартальной/годовой расстановки приоритетов. На одной странице они должны позволить читателям быстро понять проблему, ожидаемые результаты, предлагаемое решение и подход в общих чертах. Чрезвычайно полезны, когда вы погрязли в деталях проекта или сталкиваетесь с расползанием объёма работ (scope creep).

Design docs: использую их, чтобы получить обратную связь от коллег — учёных и инженеров. Они помогают выявить проблемы дизайна на ранней стадии. Более того, итерировать по design-документам можно куда быстрее, чем по системам, особенно если эти системы уже в продакшене. Обычно такой документ охватывает методологию и дизайн системы, а также включает результаты экспериментов и технические бенчмарки (если они есть).

Design docs чаще встречаются в инженерных проектах, а не так уж часто — в data science / машинном обучении. Тем не менее я нахожу их бесценными для создания более качественных ML-систем и продуктов.

After-action review (разбор по итогам): использую их для рефлексии после запуска проекта или после крупной ошибки. Если это разбор проекта, мы рассматриваем, что прошло хорошо (а что не очень), последующие действия и как сделать лучше в следующий раз. Это похоже на scrum-ретроспективу, только с бóльшим временем на размышления и оформленную в виде документа. Затем этими знаниями можно поделиться с другими командами.

Если это разбор ошибки (например, система упала), мы диагностируем первопричину и определяем последующие действия, чтобы не допустить повторения. Мы нигде не обвиняем конкретных людей. Цель — обсудить, что можно сделать лучше, и поделиться (порой болезненными) уроками со всей организацией. Amazon называет это Correction of Errors; вот как это выглядит.

Фреймворк письма: Почему, Что, Как, (Кто)

Фреймворк «Почему — Что — Как» настолько прост, что звучит как урок чтения/письма для первоклассников. И тем не менее он направляет большинство, если не все, моих рабочих документов. Мои тексты на этом сайте тоже следуют ему (другой формат — это списки, как этот и этот).

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

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

Поэтому критически важно, чтобы — прочитав этот раздел — аудитория поняла проблему и контекст. Опишите её просто, в их терминах: выгоды для клиента, бизнес-преимущества, рост продуктивности. Сравните два варианта Почему ниже; какой из них лучше подходит для бизнес-аудитории?

«Нам нужно закупить GPU-кластеры для распределённого обучения SOTA-моделей глубокого обучения, которые улучшат nDCG@10 на 20%». «Нам нужно вложиться в инфраструктуру, чтобы улучшить рекомендации для клиентов, с ожидаемым приростом конверсии и выручки на 5%».

Первый вариант, возможно, слегка утрирован, но я видел разделы Почему, которые начинались именно так. 🤦‍♂️ Это отличный способ потерять аудиторию с самого начала.

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

Один из способов сформулировать Что — через критерии успеха и ограничения. Критерии успеха определяют, как выглядит хорошее (или плохое) решение; ограничения определяют, что решения могут (и не могут) делать. Вместе они позволяют читателям оценивать предложения и принимать по ним решения, делать компромиссы и давать обратную связь.

Другой способ сформулировать Что — через требования. Бизнес-требования задают ожидаемый клиентский опыт, прирост бизнес-метрик (критерии успеха) и бюджет (ограничения). Их также можно сформулировать как продуктовые или функциональные требования. Технические требования задают пропускную способность, латентность, безопасность, приватность и т. д. — обычно как ограничения.

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

Глубина этого раздела зависит от документа. Для one-pager'ов это может быть пара абзацев о результатах поставки, с деталями в приложении. Для design docs вы, возможно, захотите включить диаграмму системного контекста, технические решения (например, централизованно или распределённо, EC2 против EMR против SageMaker), результаты офлайн-экспериментов (например, hit rate, nDCG) и бенчмарки (например, пропускная способность, латентность, число инстансов).

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

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

Документ для бизнес-руководителей будет (и должен!) выглядеть совсем иначе, чем документ для инженеров. Разные аудитории сосредоточатся на разных аспектах: боли клиентов, бизнес-результаты, ROI против технических требований, дизайнерские решения, спецификации API.

Письмо с учётом вашего Кто делает обсуждения и обратную связь более продуктивными. Мы не просим бизнес-руководителей дать обратную связь по выбору инфраструктуры и не просим devops-инженеров давать советы по бизнес-стратегии.

Как использовать фреймворк для структурирования ваших документов

Вот несколько примеров использования «Почему — Что — Как» для структурирования one-pager'а, design doc, after-action review и моих текстов на этом сайте.

Пример one-pager'а

Почему: перед нашей командой data science (в e-commerce-компании) стоит задача помочь клиентам легче находить товары. Топ-менеджеры предполагают, что лучшая находимость товаров улучшит вовлечённость клиентов и бизнес-результаты.

Что: метрики первого порядка — это вовлечённость (например, CTR) и выручка (например, конверсия, выручка за сессию). Метрики второго порядка включают использование приложения (например, daily active users) и удержание (например, monthly active users). Ограничения задаются через бюджет и сроки.

Как: команда рассмотрела несколько онлайн- (например, поиск, рекомендации) и офлайн- (например, таргетированные письма, push-уведомления) подходов. Их анализ показал, что бóльшая часть активности клиентов происходит на страницах товаров. Поэтому предполагается, что наибольший ROI даст item-to-item (i2i) рекомендатель — на страницах товаров.

Приложение: разбивка по входящим каналам и активности на сайте, обзор различных подходов, подробное объяснение рекомендательных систем.

Пример design-документа

Почему: сейчас на наших страницах товаров нет способа дать пользователям находить похожие товары. Чтобы это исправить, мы строим i2i-рекомендатель для улучшения находимости товаров и вовлечённости клиентов.

Что: бизнес-требования схожи с указанными в one-pager'е, но более детальны. Мы вместе с командами веб- и мобильного приложения определили технические требования, такие как пропускная способность (> 1000 запросов в секунду), латентность (<150мс на p99) и доступность (99% аптайма). Наши ограничения включают стоимость (<10% от сгенерированной выручки, с абсолютным порогом) и точки интеграции.

Как: это будет самый «мясистый» раздел design doc. Мы поделимся методологией и общим дизайном, включая диаграммы системного контекста, технический выбор, начальные офлайн-метрики оценки (для ML), а также рассмотрим аспекты пропускной способности, латентности, стоимости, безопасности, приватности данных, интеграции и т. д.

Приложение: компромиссы, что рассматривалось, но было исключено, спецификации API, UI и т. д.

Пример after-action review

Контекст: в день пиковых продаж (11.11) i2i-рекомендатель некоторое время не отображался на страницах товаров. Это обнаружили категорийные менеджеры, проверявшие скидки на свои товары.

Почему (5 почему): всплеск трафика привёл к росту латентности (>150мс) при выдаче рекомендаций. Возросшая латентность привела к тому, что виджет рекомендателя отваливался по таймауту — и не показывался — на страницах товаров. Хотя автомасштабирование было включено, оно упёрлось в квоты на инстансы и не смогло масштабироваться дальше. Мы проводили нагрузочные тесты при трафике в 3 раза выше обычного, но их оказалось недостаточно, так как пиковый трафик был в 30 раз выше нормы. Кроме того, проблему не обнаружили раньше, потому что наши алармы не учитывали ситуацию, когда результаты не отображаются.

Что: клиентский опыт не пострадал, так как страницы товаров продолжали загружаться в пределах ожидаемой латентности. Тем не менее невыдача рекомендаций привела к потере ожидаемой выручки. Исходя из выручки, приписанной рекомендателю в остальное время дня, оценочная потеря составляет $x.

Как: мы предпримем следующие действия, чтобы предотвратить повторение инцидента и раньше обнаруживать похожие проблемы. Указаны их ответственные.

Приложение: хронология инцидента, общие уроки и рекомендации.

Пример личного текста

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

Что: какие документы я пишу? Привести несколько примеров.

Как: объяснить подход «Почему — Что — Как» и показать примеры того, как я его использую.

Писать документы дорого, но дёшево

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

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

Если задача неоднозначна, предлагаемое решение спорно, требуемые усилия велики (> 3–6 месяцев) и/или нужен консенсус нескольких команд, то начать с документа сэкономит усилия в средне- и долгосрочной перспективе.

Поэтому, прежде чем начать следующий проект, напишите документ по схеме «Почему — Что — Как». Вот подробнее об one-pager'ах (и других вещах, которые я делаю перед началом проекта).

Запуская AWS, прежде чем написать хоть строчку кода, инженеры потратили 18 месяцев на написание документов о том, как лучше всего обслуживать клиентов. Точно так же, прежде чем что-то строить, я пишу документы. Здесь я поделюсь тремя документами, которые пишу, и раскрою фреймворк, который их структурируетhttps://t.co/6hNt4F1Qwz— Eugene Yan (@eugeneyan) 2 марта 2021

Спасибо Yang Xinyi за чтение черновиков.

Если это оказалось полезным, пожалуйста, цитируйте эту заметку так:

Yan, Ziyou. (Feb 2021). How to Write Better with The Why, What, How Framework. eugeneyan.com. https://eugeneyan.com/writing/writing-docs-why-what-how/.

или

@article{yan2021why, title = {How to Write Better with The Why, What, How Framework}, author = {Yan, Ziyou}, journal = {eugeneyan.com}, year = {2021}, month = {Feb}, url = {https://eugeneyan.com/writing/writing-docs-why-what-how/} }

Присоединяйтесь к 11 800+ читателей, получающих обновления о машинном обучении, RecSys, LLM и инженерии.