Two-way writeups: Coda’s secret to shipping fast

Explore

Two-way writeups: Coda’s secret to shipping fast

Three simple tips to drive results from written documents.

Lane Shackleton

At Coda, we pride ourselves in shipping fast with high quality. Don’t take my word for it, check out

coda.io/updates

⁠

to see the pace of improvements for our customers. One of our secrets? We drive clarity and decision-making in docs we call two-way write ups. Now, we’re sharing how you can too.

Before Coda, I spent nine years at Google and YouTube. ‘Writeups’ were a standard tool used by product, design, and engineering teams. A ‘writeup’ is a catch-all term for a written document that helps a team achieve their objective. They get used for many purposes, from generating ideas, to driving decision making, to ensuring clear communication. More on this later.

⁠

Evolving from slide presentations to writeups.

⁠

⁠

Stepping back for a moment, I’ve noticed a broader evolution in the way work gets presented and discussed. Every 15-20 years, we’ve seen a significant change. The change is often driven by an evolution in tools and desired outcomes. The first phase started in the 1980’s with the invention and popularization of Powerpoint. The tool was a breakthrough that enabled anyone to directly manipulate shapes and imagery in order to create a clear story for the audience. Two decades later, the advent of online collaborative documents (Google Docs) and Amazon six-pagers, drove the business world toward a ‘write first’ cultural transition. Now, it’s the 2020’s and we’re ready for the next leap.

Phase #1: Slide Presentations, aka the Powerpoint Generation

Powerpoint launched in 1987, few people at the time understood how big an impact the product would have over the next two decades. But our experience with slides today feels different. We’ve all been there. A presenter endlessly talks through bullet points on dozens of slides while the audience’s attention wanders. The presenter is either derailed with real-time questions, or the audience waits impatiently till the end to have the important discussion. Many companies have realized the inefficiency of Powerpoint slides and moved their

rituals

⁠

toward Phase #2.

Phase #2: One-Way Writeups, aka Amazon Six-Page Memos

One-way writeups are the practice of sending out a document for comments instead of creating slides to describe the work. How’d they come about? The first big step happened when Jeff Bezos famously wrote his "No more PowerPoint" memo in 2004. Amazon introduced a

six-pager ritual

⁠

that has now become synonymous with their management style and has been mimicked by thousands of teams around the world. The second step happened in 2006, when Google Docs launched. Back then, real-time collaborative editing was a completely magical breakthrough. Fun nerdy side-note, I used to chat with my girlfriend (now wife) in early internal versions of Google Wave.

While these two steps were not coordinated, they had a compounding effect on each other. The shift from pure presentations to one-way writeups was a significant improvement. As a writer, the focus was on the content and not the presentation design. As the audience, you could get into a rich discussion with details laid out in prose instead of wading endlessly through slides. At the same time though, the right margin in a Google Doc always felt like the wrong place to have hard discussions. And with the growing importance of asynchronous and online collaboration, facilitating these discussions becomes a critical need propelling us towards Phase #3.

Phase #3: Two-Way Writeups

I believe the next phase is what we call ‘two-way writeups’ at Coda. Similar to one-way writeups, they start with a clearly framed or articulated set of ideas. But picking up where one-way writeups fall short, two-way writeups create a structured and interactive conversation. They guide reviewers to give actionable feedback. They create an inclusive environment by enabling anyone to clearly state their sentiment and ask questions that others can upvote. In short, they are more efficient at moving a team toward their goal.

Most writeups are one-way, but it’s time to bring collaboration out of the comments and into the writeup itself. Here’s how you can redefine writeups with your team.

⁠

Three simple tips that redefine writeups.

When you send a Google Doc over email and ask for comments, it’s like printing a piece of paper and putting it on people’s desk. As the author, you’ve done all the talking. The interaction of your audience is relegated to the confining right margin space dedicated to comments in a Google Doc. Or worse, the feedback ends up in a long, siloed email thread. As one prominent CEO put it to me:

It feels like the most important decisions in our company are jammed into the 100 pixel panel hanging off the side of our Google Docs. Is that really the best we can do?

As I see it, there are three problems with one-way writeups:

You don’t know who read the doc.

The feedback is unstructured, and all appears equally important.

The most important questions get buried in long comment threads.

In contrast, two-way writeups treat writeups as conversations, guided toward progress. They start with the premise that questions and feedback are a core part of iterating quickly toward a solution. So let’s look at how our team addresses the problems above with our own writeups, powered by Coda.

(1) Done Reading: know who read the writeup, then get moving.

The problem: At YouTube, in the hours before reviewing a writeup in a meeting, I’d find myself regularly checking the avatars of who was in the Google Doc. Why? I wanted to know which reviewers had read the proposal and which had not. It’s a silly behavior, but when you put many hours into a writeup, you want to know who has read it.

The solution: Knowing exactly who has read the writeup enables you to start the discussion when key stakeholders have finished reading. No more asking ‘Who has read the doc?’ and scrolling through Zoom tiles looking for raised hands. Simply put a

reaction

⁠

at the bottom of your writeup, asking who has read it. For long writeups, you can include 2-3 done reading buttons to encourage engagement along the way.

⁠

Demo: You can type /done reading to add this button at the end of your writeup.

Done reading? Click here:

⁠

(2) Pulse: gather structured feedback, then read each other’s.

The problem: At YouTube, using one-way writeups, we’d have mega-comment threads. You’ve probably seen these serious multi-paragraph debates in the tiny right margin for comments. The mega-threads were a symptom of a deeper problem. The teams were getting unstructured feedback, and it all looked the same.

A comment on wording looks the same as a comment with fundamental or blocking feedback. The result was feedback that is hard to parse, prioritize and act upon. The way the feedback was gathered slowed down the iteration process.

The solution: Instead of asking people to simply comment on your doc, ask them a specific question that you need answered to make progress. It can be as simple as ‘How do you feel about the proposal?’ to something more targeted like ‘What didn’t we think about that we should?’

At Coda, we have a ritual called ‘Pulse’ where we gather sentiment and feedback at the end of a writeup. For a writeup that is sent over email or Slack, the author might ask for the group’s pulse by a certain date. For a writeup that is being reviewed in a meeting, sentiment is normally gathered as part of pre-read, or at the start of the meeting.

There are two steps to the ritual, with an example below.

First step, the feedback table is filtered to only to the person writing the feedback. Since you can’t see everyone else's thoughts, you’re not biased by their feedback and can form you own opinions.

Second step, we ‘toggle’ to show everyone else’s feedback. Now everyone can read each others thoughts. Enabling the group to read their peer’s feedback is an efficient and precise way to see where everyone stands on the writeup.

⁠

Demo: you can type /pulse to add a table to gather answers to a key question in any writeup.

⁠

Toggle to show everyone's pulse check (

3

⁠

submitted. Average pulse check of

3.67

⁠

)

How do you feel about the writeup?

How do you feel about the writeup?

Pulse Check

Reflection

Submitted by

Nice writeup!

I find sharing rituals amongst teams like this enables each team to make it their own. As an example, I’ve seen teams customize the pulse ritual in lots of different ways to fit their specific situations.

Shishir Mehrotra

I love how simple yet effective the tools in this doc are. For example, the Done Reading reaction resonated quite a bit with me because I always wonder how many people have actually read my writeups. That simple tool could replace dozens of unnecessary meetings I’ve recently sat in!

Justin Hales

I think I’m in the wrong doc?

Erin Dame

There are no rows in this table

⁠

The ritual typically ends in a few different ways.

No meeting, keep executing: if the writeup was sent for asynchronous feedback, the team will gather sentiment and keep iterating based on the feedback they get.

Positive sentiment, cancel meeting: if the writeup was sent as a pre-read to a meeting, and the sentiment is universally positive, we may decide to shorten or cancel the meeting.

Diverse and deep sentiment, figure out which question to answer first: other times, the feedback and sentiments are across the spectrum and it’s clear that we need more time to digest the feedback carefully to ensure we’re answering the most important questions first (see next step).

In all cases though, we gain an understanding of how the entire team feels about the proposal, and the team can base their next actions on a clear, directed, and comprehensive set of feedback.

A few tips & variations for using ‘Pulse’

Send long or complex writeups as pre-reads. When a writeup becomes particularly detailed, or the decision particularly complex, it’s almost always a good idea to ask reviewers to pre-read the writeup and add detailed sentiment prior to the meeting. The feedback giver will appreciate the additional time to think about the topic, and ensure they are providing feedback that is commensurate with the depth of the writeup.

Add a ‘Conviction’ column. With larger groups, some of the audience might have a lot of context on the problem space, while others don’t. In these instances, I find it helpful to add a second column (in addition to pulse check) that asks the feedback author for their conviction on their feedback. It’s a helpful way to give people a way to express that they may have low conviction (perhaps because the team has more expertise) or high conviction on their feedback (perhaps because they have some piece of important context). Either way, I find it helpful to know how strongly someone feels about their feedback.

Have some fun with icons. With Scale columns in Coda, you can choose different icons for your ‘Pulse’ tables (shown below). Have a spicy topic? Use chili peppers as the scale to diffuse the tension. Want to signal urgency in a pulse check? Use the alarm bell to orient the audience.

⁠

Screen Shot 2021-07-14 at 2.43.09 PM.png

⁠

Craft your question. Spend a few minutes intentionally crafting the question you think will move the team forward. Some example pulse questions that get asked in our writeups:

How do you feel about the proposal?

Are there alternatives we should consider?

What concerns do you have?

What’s are the most important questions to address next?

(3) Dory: run organized meetings, focus on most important questions.

The problem: It’s easy to have a meeting derailed by unimportant questions. Worse, it’s frustrating to have the questions dominated by the highest paid (or loudest) person in the room. In both scenarios, the group leaves the meeting with lingering questions from important stakeholders. And key decisions are slowed because the discussions required to make the decisions are never prioritized.

In one-way writeups, you typically read and pull questions out of comment threads. But this is an inefficient and imprecise way to ensure you’re addressing the most important questions.

The solution: Pulling out the most important questions, the questions that provide answers to other downstream questions, is a point of pride for Codans. We even named it and wrote about it; they’re called

Eigenquestions

⁠

. So it’s not surprising that when we discuss writeups, a core ritual is providing the team a way to enumerate their questions and vote on the most important ones to discuss.

We use a table of questions called ‘Dory.’ It’s named after the fish in

Finding Nemo

⁠

that asks all the questions :)

After reading the writeup, the team adds questions to a table at the bottom of the writeup. Then the team reads through each others and upvotes the questions they think are important to discuss. Sometimes, we also downvote questions that have been discussed before or are better for a smaller group to dive into. The table automatically sorts the questions based on net votes (i.e. upvotes - downvotes).

⁠

Demo: you can type /dory to add a table to gather questions in any writeup.

Dory: questions to discuss

Dory: questions to discuss

Question

Author

Upvote

Downvote

What decision(s) do we need to make today (vs later)?

thumbs-down reaction, you have not reacted

What’s the core problem we’re trying to solve?

How will we know if/when we’re successful?

There are no rows in this table

⁠

And that’s it. By crowdsourcing the discussion topics and quickly prioritizing with voting, key stakeholders can rest assured that they are discussing the questions on everyone’s mind, and not just the loudest or highest paid person.

A few tips & variations for using ‘Dory’

Categorize or group the questions to prioritize the discussion. Often, you’ll notice questions will be variants on a similar theme. When we see this happening, it’s common for the author of the writeup to add a new select-list column for ‘theme’ or ‘category.’ They will then quickly go through and categorize the questions. Categorizing the questions will enable them to

‘Group’

⁠

the new column so that it’s easy to go through categories or themes of questions.

Pull out the Eigenquestions. Early in a project’s lifecycle (like the wallow or frame phase from the beginning), a team may still be searching for the key question that helps answer other downstream questions (the

Eigenquestion

⁠

). In this case, it can be helpful to add another

‘Reaction’

⁠

column and ask the audience to vote on which questions they think are Eigenquestions. Sometimes, you’ll get critical mass on one question that feels like it should be answered. And other times, it will generate a good discussion on how we don’t quite have the right question to answer yet.

Try two-way writeups to gather structured feedback and drive clear decision-making.

Two-way writeups are an intentionally crafted ritual, used by all teams at Coda to move fast while remaining thoughtful. They start by acknowledging that writeups are not static, and that writeups are created to move the team closer to their objectives. They guide reviewers into giving clear and structured feedback. Lastly, they create inclusive environments by ensuring the most important questions, from anyone on the team, get surfaced and answered.

I’ve found two-way writeups are significantly more effective making teams feel autonomous and efficient than one-way writeups. Give them a try with your team and let me know what you think.

⁠

👉 Want to see examples?

If you’re starting a new writeup checkout →

Blank Two-Way Writeup

⁠

If you want to see how to incorporate existing slides →

Example: Slide + Writeups

⁠

If you want to see a real example from inside Coda →

Example: Inline toolbar

⁠

Frequently Asked Questions

What is (and isn’t) a writeup?

'Writeup’ is simply a catch-all term for a written doc that helps move a team toward their goal. Some example objectives include things like: ideating around a new capability, proposing a specific course of action, changing a key decision that impacts other teams, modifying a team process, and much more. To achieve these objectives, the team uses a writeup to structure a discussion and drive toward their objective.

Then what isn’t a writeup? In the term writeup, I don’t include things like wikis, documentation or other writing that isn’t intended for input and iteration.

When are writeups used at Coda?

At Coda, writeups reflect the stage of a team’s idea, decision, or project. When asking for feedback on writeups, teams begin by stating explicitly what stage they are in, so that reviewers understand the context using a shared language.

The five stages we use are:

Wallow — the team is early, exploring, and/or uncertain of the the problem and solutions.

Frame — the team has framed the proposal, discussion, or decision.

Propose — the team has a specific proposal they’d like feedback on.

Close — the team is actively trying to close a big decision.

Act — the team is executing & wants to communicate the plan to get final questions or feedback.

Concretely, here are a few common examples of writeups:

A feedback writeup at the wallow phase, where the team gathered and summarized feedback.

A strategy two-pager at the frame phase, where the team needs feedback on strategy framing.

A product brief at the propose phase, where the team needs feedback on a specific proposal.

An Engineering design doc at the close phase, where the team needs to finalize a technical choice.

A hiring plan at the act phase, where the team wants to communicate to the broader organization.

⁠

How are writeups used at Coda?

At Coda, teams use writeups however they see fit to achieve their objective. We don’t expect teams to progress linearly and cleanly through the five stages above. We’re flexible and trust our team’s judgement. As a simple example, if the problem space is well-understood, the first writeup maybe a product brief at the propose phase.

Like many cultures that emphasize writeups, they get used in three main ways:

To gather asynchronous feedback (outside of a meeting). In this model, the team usually starts by writing up a doc to clarify their thinking and gather feedback. The starting assumption is usually that they’ll gather feedback in the doc itself, and use that feedback to continue iterating or progressing toward their objective. If the writeup has particular sticking points, or it’s clear that it’d be faster to resolve by discussing in a meeting, they may evolve the writeup for the purposes of driving an effective in-meeting discussion (#2).

To drive effective discussion (in a meeting). In this model, the team usually knows the topic will require discussion in a meeting, so the writeup is structured to ensure it’s driving an effective in-meeting interaction. That could include a pre-read before the meeting or starting the meeting by reading, but the idea is to direct the in-meeting discussion in the most effective way, so that the team can make progress.

To communicate a decision or plan. In this model, the writeup is usually meant to be a clear artifact of a decision or plan. The focus is less on feedback and subsequent iteration, and more on making sure the organization understands what’s happening, why it’s important and how it might affect them.

Why are writeups so critical?

Our approach to writeups is one key to how we deliver high quality software quickly.

Most writeups lead to unstructured feedback, disorganized reviews and/or ambiguous outcomes. The result is disempowered, frustrated teams. And disempowered teams ship slowly. Decisions take too long, people try to side-step reviews, and the internal process manifests in a worse customer experience.

The question is, how might we take a common tool for things like decision-making, and ensure it’s efficient and effective for teams.

⁠

Acknowledgements

Thank you to all those that gave feedback and contributed to the writeup!

Erin Dame, Justin Hales, Shishir Mehrotra, Nathan Penner, Angad Singh, Rachel Colson, David Kossnick, SiNing Chan, Khanh Le, Matt Shearon, Zindzi McCormick, Luke Segars, Shiva Rajaraman, Rushabh Doshi, Jen Huang Gil, Paul Stiff, Jonathan Rochelle, Phil Farhi, Noam Lovinsky, Lenny Rachitsky, Nikhil Goel, Emily Flannery, Sumner Paine, Neena Kamath, Adil Tobaa, Yuhki Yamashita, Robin Bigio, Eddie Lin

PS - to see other docs from Lane, checkout

coda.io/@lshackleton

⁠

Cover photo credit: Thanos Pal via Unsplash

⁠

A few of the 25,000+ teams that 🏃‍♀️ on Coda.

⁠

a77eed08d9f915aabec0346b67a40b7ec93457a9864e51bde1e9239fad175c59624ad1bd252ec5041198bc8e9a52ce31b441ab4767fbb714b9172474278d0b29434f118c46abc5c7a7377f4ad1ea733677ca74d97bc8661e4bbfde8d9cdafabc285f5616.jpeg

⁠

Coda is an all-in-one doc for your team’s unique processes — the rituals that help you succeed. Teams that use Coda get rid of hundreds of documents, spreadsheets, and even bespoke apps, to work quickly and clearly in one place. This template is a Coda doc. Click around to explore.

Find out how to Coda-fy your rituals.

⁠

Connect with a Rituals Architect

⁠

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.