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

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

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

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

[ writing engineering productivity 🩷 🔥 ] · 10 min read

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

Here’s a story from the early days of Amazon Web Services: Before writing any code, engineers spent 18 months contemplating and writing documents on how best to serve the customer. Amazon believes this is the fastest way to work—thinking deeply about what the customer needs before executing on that rigorously refined vision.

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

Similarly, as a data scientist, though I solve problems via code, a lot of the work happens before writing any code. Such work takes the form of thinking and/via writing documents. This is especially so in Amazon, which is famous for its writing culture.

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

This post (and the next) answers the most voted-for question on the topic poll:

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

How to write design documents for data science/machine learning projects?

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

I’ll start by sharing three documents I’ve written: one-pagers, design documents, and after action reviews. Then, I’ll reveal the framework I use to structure most of my writing, including this post. In the next post, we’ll discuss design docs.

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

One-pagers, design docs, after-action reviews

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

I usually write three types of documents when building/operating a system. The first two help to get alignment and feedback; the last is used to reflect—all three assist with thinking deeply and improving outcomes.

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

The three types of documents written during a project

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

One-pagers: I use these to achieve alignment with business/product stakeholders. Also used as background memos for quarterly/yearly prioritization. In a single page, they should allow readers to quickly understand the problem, expected outcomes, proposed solution, and high-level approach. Extremely useful to reference when you’re deep in the weeds of a project, or encounter scope creep.

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

Design docs: I use these to get feedback from fellow scientists and engineers. They help identify design issues early in the process. Furthermore, you can iterate on design docs more rapidly than on systems, especially if said systems are already in production. It usually covers methodology and system design, and includes experiment results and technical benchmarks (if available).

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

Design docs are more commonly seen in engineering projects; not so much for data science/machine learning. Nonetheless, I’ve found it invaluable for building better ML systems and products.

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

After-action reviews: I use these to reflect after shipping a project, or after a major error. If it’s a project review, we cover what went well (and not so well), follow-up actions, and how to do better next time. It’s like a scrum retrospective, except with more time to think and written as a document. The knowledge can then be shared with other teams.

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

If it’s an error review (e.g., the system goes down), we diagnose the root cause and identify follow-up actions to prevent reoccurrence. Nowhere do we blame individuals. The intent is to discuss what we can do better and share the (sometimes painful) lessons with the greater organization. Amazon calls these Correction of Errors; here’s how it looks like.

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

Writing framework: Why, What, How, (Who)

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

The Why-What-How framework is so simple that it sounds like a reading/writing lesson for first graders. Nonetheless, it guides most, if not all, of my work documents. My writing on this site also follows it (the other format being lists like this and this).

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

Why: Start by explaining Why the document is important. This is often framed around the problem or opportunity we want to address, and the expected benefits. We might also answer the question of Why now?

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

Think of this as the hook for your document. After reading the Why, readers should feel compelled to blaze through the rest of your doc (and hopefully commit to your proposal). In resource-strapped environments (e.g., start-ups), this section convinces decision-makers to invest resources into your idea.

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

Thus, it’s critical that—after reading this section—your audience understands the problem and context. Describe it simply in their terms: customer benefits, business gains, productivity improvements. Contrast the two Whys below; which is better suited for a business audience?

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

“We need to procure GPU clusters for distributed training of SOTA deep learning models that will improve nDCG@10 by 20%.”

“We need to invest in infrastructure to improve customer recommendations, with an expected conversion and revenue uplift of 5%.”

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

The first one might be a tad exaggerated, but I’ve seen Whys that start like that. 🤦‍♂️ It’s a great way to lose the audience from the get-go.

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

What: After the audience is convinced we should solve the problem, share what a good solution looks like. What are the expected outcomes and ways to measure them?

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

One way to frame What is via measures of success and constraints. Measures of success define what a good (or bad) solution looks like; constraints define what solutions can (and cannot) do. Together, they enable readers to evaluate and decide on proposals, make trade-offs, and provide feedback.

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

Another way of framing What is via requirements. Business requirements specify the expected customer experience, uplift to business metrics (success measures), and budget (constraints). They might also be framed as product or functional requirements. Technical requirements specify throughput, latency, security, privacy, etc., usually as constraints.

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

How: Finally, explain How you’ll achieve the Why and What. This includes methodology, high-level design, tech decisions, etc. It’s also useful to add how you’re not implementing it (i.e., out of scope).

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

The depth of this section depends on the document. For one-pagers, it could be a paragraph or two on deliverables, with details in the appendix. For design docs, you may want to include a system context diagram, tech decisions (e.g., centralized vs. distributed, EC2 vs. EMR vs. SageMaker), offline experiment results (e.g., hit rate, nDCG), and benchmarks (e.g., throughput, latency, instance count).

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

Having a solid Why and What provides context and makes this section easier to write. It also makes it easier for readers to evaluate and give feedback on your idea. Conversely, poorly articulated intent and requirements make it difficult to spot a good solution even when it’s in front of us.

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

(Who): While writing docs, we should keep our audience in mind. Although Who may not show up as a section in the doc, it’ll influence how it turns out (topics, depth, language).

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

A document for business leaders will (and should!) look very different from a document for engineers. Different audiences will focus on different aspects: customer pain points, business outcomes, ROI vs. technical requirements, design choices, API specifications.

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

Writing with your Who in mind makes for more productive discussions and feedback. We don’t ask business leaders for feedback on infra choices, and we don’t ask devops engineers for guidance on business strategy.

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

How to use the framework to structure your docs

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

Here are some examples of using Why-What-How to structure a one-pager, design doc, after-action review, and my writing on this site.

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

One-pager example

Пример one-pager'а

Why: Our data science team (in an e-commerce company) is challenged to help customers discover products easier. Senior leaders hypothesize that better product discovery will improve customer engagement and business outcomes.

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

What: First-order metrics are engagement (e.g., CTR) and revenue (e.g., conversion, revenue per session). Second-order metrics include app usage (e.g., daily active users) and retention (e.g., monthly active users). Constraints are set via a budget and timeline.

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

How: The team considered several online (e.g., search, recommendations) and offline (e.g., targeted emails, push notifications) approaches. Their analysis showed the majority of customer activity occurs on product pages. Thus, an item-to-item (i2i) recommender—on product pages—is hypothesized to yield the greatest ROI.

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

Appendix: Breakdown of inbound channels and site activity, overview of the various approaches, detailed explanation on recommendation systems.

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

Design document example

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

Why: Currently, our product pages lack a way for users to discover similar products. To address this, we are building an i2i recommender to improve product discoverability and customer engagement.

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

What: Business requirements are similar to those specified in the one-pager, albeit with greater detail. We collaborated with the web and mobile app teams to define technical requirements such as throughput (> 1,000 requests per second), latency (<150ms at p99), and availability (99% uptime). Our constraints include cost (<10% of revenue generated, with an absolute threshold) and integration points.

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

How: This will be the meatiest section of the design doc. We’ll share the methodology and high-level design, including system-context-diagrams, tech choices, initial offline evaluation metrics (for ML), and address aspects of throughput, latency, cost, security, data privacy, integration, etc.

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

Appendix: Trade-offs, what was considered but excluded, API specs, UI, etc.

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

After-action review example

Пример after-action review

Context: During a peak sales day (11/11), the i2i recommender was not visible on product pages for a period of time. This was discovered by category managers inspecting their products’ discounts.

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

Why (5 Whys): The spike in traffic led to increased latency (>150ms) when serving recommendations. The increased latency led to the recommender widget timing out—and not being shown—on product pages. While autoscaling was enabled, it hit the instance quotas and could not scale beyond that. Though we conducted load tests at 3x normal traffic, these were insufficient as peak traffic was 30x normal traffic. In addition, it was not discovered earlier because our alarms didn’t account for results not being displayed.

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

What: Customer experience was unaffected as product pages continued to load within expected latency. Nonetheless, not serving recommendations led to loss of expected revenue. Based on revenue attributed to the recommender during the rest of the day, the estimated loss is $x.

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

How: We will take these follow-up actions to prevent a repeated incident and detect similar issues earlier. These are their respective owners.

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

Appendix: Timeline of incident, overall learnings and recommendations.

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

Personal writing example

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

Why: Why is writing documents important? Share anecdote. Mention it’s highly voted-for.

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

What: What documents do I write? Share some examples.

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

How: Explain the Why-What-How approach and share examples of how I use it.

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

Writing docs is expensive, but cheap

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

Writing documents cost money. They take time to write, review, and iterate on—this is time that could have been spent on implementation.

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

Nonetheless, writing is a cheap way to ensure we solve the right problems in the right way. They save money by helping teams avoid rabbit holes or building systems that aren’t used. They also help align stakeholders, improve initial ideas, and scale knowledge.

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

If the problem is ambiguous, the proposed solution contentious, the effort required high (> 3-6 months), and/or consensus is required across multiple teams, starting with a document will save effort in the medium to long term.

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

So before you start your next project, write a document using Why-What-How. Here’s more detail about one-pagers (and other things I do before starting a project).

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

While starting AWS, before writing any code, engineers spent 18 months writing documents on how best to serve customers.

Similarly, before I build anything, I write docs. Here, I'll share three docs I write and reveal the framework that structures themhttps://t.co/6hNt4F1Qwz

— Eugene Yan (@eugeneyan) March 2, 2021

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

Thanks to Yang Xinyi for reading drafts of this.

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

If you found this useful, please cite this write-up as:

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

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/.

or

или

@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/} }

Join 11,800+ readers getting updates on machine learning, RecSys, LLMs, and engineering.

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