Skip to content
Two-way writeups: Coda’s secret to shipping fast
Share
Explore
Two-way writeups: Coda’s secret to shipping fast
Three simple tips to ensure you're driving results from written documents.
At Coda, we pride ourselves in shipping fast with high quality. Don’t take my word for it, check out
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
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
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.
T
he
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
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
(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 check a box 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.
Check to show everyone's pulse check (
3
submitted. Average pulse check of
3.67
)
How do you feel about the writeup?
Pulse Check
Reflection
Submitted by
1
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.
2
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!
3
I think I’m in the wrong doc?
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’
(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
. 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
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: y
ou can type
/dory
to add a table to gather questions in any writeup.
Dory: questions to discuss0QuestionAuthorUpvoteDownvote1What decision(s) do we need to make today (vs later)?
4
12What’s the core problem we’re trying to solve?
313How will we know if/when we’re successful?
2There are no rows in this table
Dory: questions to discuss
Question
Author
Upvote
Downvote
1
What decision(s) do we need to make today (vs later)?
4
1
2
What’s the core problem we’re trying to solve?
3
1
3
How will we know if/when we’re successful?
2
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’
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?
Frequently Asked Questions
What is (and isn’t) a writeup?
When are writeups used at Coda?
How are writeups used at Coda?
Why are writeups so critical?
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
Cover photo credit: Thanos Pal via Unsplash
A few of the 25,000+ teams that 🏃♀️ on Coda.
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.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.