Skip to content
Share
Explore
Two-way writeups: Coda’s secret to shipping fast
Two-way writeups: Coda’s secret to shipping fast
Three simple tips to drive 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 2005 when Writely was launched and later acquired by Google. The next year, in 2006, 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:
As I see it, there are three problems with one-way writeups:
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) 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 (submitted. Average pulse check of)
3
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.
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.
(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: you can type /dory to add a table to gather questions in any writeup.
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.
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?
'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:
Concretely, here are a few common examples of writeups:
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:
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
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.
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.