Skip to content
Two-way writeups: Coda’s secret to shipping fast
Share
Explore
Examples

Example: Inline toolbar

A real Coda product launch example, using two-way writeup.
The writeup below is a real proposal shared internally at Coda for the
feature that shipped in April 2021. It’s been slightly edited to remove confidential information and add clarity for non-Coda audiences. The writeup was done by
and
from our Product and Design team.

As you read, pay attention to:
How the writeup starts with clear background and context for the reader.
How the writeup is put forth early, well ahead of launch to ensure plenty of time for feedback, follow-ups and partnership with the rest of the teams.
How interactivity is strategically placed — ‘mark as read’ buttons placed mid-way through since this was read by a group during a meeting, structured table of concerns that you can add to as a reader/collaborator, structured place for questions with sorting for upvotes, and a pulse check for overall thoughts at the bottom when you’re done reading.

Background

As Coda transitions toward honing the simple cases, things like the visual design and emotional feeling of the product become more important. In the past, we saw evidence of this with the launch of features like centered content and cover photos, and especially with the
. While we knew those features would be impactful ahead of time, we were still pleasantly surprised at the reception from makers and the continued enthusiasm for the dozens of small improvements we’ve done as a follow-up.

Since Coda’s inception, we’ve debated whether the toolbar should be fixed or inline. More recently, the inline toolbar was one of the features that we scoped out of the original visual refresh project. Our guiding principle behind the visual refresh was to minimize Coda UI and make more space for the user content to shine. In the same vein, the top toolbar is a piece of UI that permanently takes up real estate on the screen, even though it is not actually used that often. A majority of people who write and edit docs in a given week don’t use the toolbar. More importantly, the toolbar makes Coda docs feel more cluttered and “work in progress” for viewers and contributors. For that reason, we believe that switching to the inline toolbar will make Coda docs feel more lightweight for simple cases and more presentable for sharing with others.

PRD-21003-Header_Toolbar-800x600.gif

While we have always believed this change is the right direction to go, we had scoped it out in the past because we wanted to make sure to manage the transition well when we do. We decided to make this change now because it also blocks our ability to support key upcoming launches.

Who moved my cheese?

As with many other products, design changes in the UI can be controversial and draw backlash from makers. The inline toolbar is an especially sharp case of this change because it requires some adjustment to a new way of taking key actions. Moreover, there are some small scenarios that may have more friction with the inline toolbar, such as formatting the text on a blank line or in a single cell.

Given these constraints, we want to take a careful and considered approach to designing and launching this feature. Through our internal testing over the last 2+ weeks, we have received a lot of great feedback from Codans who are power users of Coda. We have run many user tests with new users across the baseline and inline toolbar variants. We plan to do additional testing and monitoring, but would love to share out what we have learned so far to collect input.

I’ve read this far
3

Concerns

Besides the transition, here are the key buckets of concerns that we have heard so far with the inline toolbar, along with our current thinking on how to mitigate them.
Concern
Description
Mitigation
1
Familiarity
Coda feels less familiar as a doc surface to those coming from Word, Google Docs as well as existing Coda users.
From user testing, there was no observed difference in familiarity - users in the inline toolbar variant labeled Coda as simple or similar to other tools just as often as users in the baseline variant.
Consistent with our “right over familiar” value.
2
Discoverability
It might be harder to find how to do specific things like adding a hyperlink, emoji, comment etc before selecting.
From user testing, we did not find this to be a concern. Even when users had the toolbar, they still used / commands and Explore far more often to find things.
We will watch specific metrics to ensure this doesn’t get affected.
We will continue iterating to promote the toolbar in the UI at the appropriate moments (placeholder text, right click menu, / menu etc).
3
Convenience
The toolbar doesn’t always show when I need to use it. I have to select something first e.g. blank line, single cell/column etc.
Hold down Command key - tell users this reactively and find ways to teach this in the product proactively.
Use / commands e.g.
/bold
,
/link
,
/red
,
/emoji
,
/list
.
We’re adding quick paragraph style switching in the 3-dot menu.
We’ll add an option in the right-click menu on a cell/row/column.
4
Noisiness
The toolbar sometimes shows up when I don’t need it, for example if I select text to read or select multiple rows/columns to move.
We have tried to strike a balance but would love feedback to fine-tune the heuristic
Find ways to make the toolbar unobstructive - e.g. make it smaller, transparent etc.
Add a delay between when you select and the toolbar shows up.
There are no rows in this table


Motivation

While we are cognizant of the concerns and want to do our best to address them, we believe there are still a number of important reasons to ship the inline toolbar. Here are the key reasons we’ve identified and please add comments to share your thoughts on them:
Reason
Description
Expected impact
1
More beautiful & presentable
The lack of an ever-present toolbar means that docs look more ready to share or present, with or without cover photos.
People may be more likely to share Coda docs with their team or publish them to make their ideas shine.
2
Cleaner & simpler
A majority of weekly active editors never use the toolbar at all, so hiding the toolbar would make Coda feel more lightweight for simple cases.
People may be more likely to use and promote Coda for simpler cases like jotting down notes or a project brief.
3
Highlight what’s unique
Go from having ~15 buttons at the top of the page to just 5, making key actions like Share and Explore more prominent.
Increase in users clicking Share and Explore, especially Gen 1 users coming into a doc where Explore is not open.
4
Closer at hand
Since the inline toolbar shows up right next to your selection, it saves time compared to taking your mouse all the way up.
Applying a format using the toolbar takes less time and mouse travel than before.
5
Available in more surfaces
Users can now see the inline toolbar in places they couldn’t before, including row modal, comments, and also planned new features.
Increase in users applying formatting in row modal & comments, and unblocking future capabilities.
6
Contextual buttons
Since the toolbar is not always visible, we can show a different set of items based on your selection e.g. folding for headings.
Increase in discoverability of features like folding (and other things in the future like creating a view of a table).
There are no rows in this table


Plan forward

Continue learning:
We are still working on many ‘P1’ issues and feedback and refining a lot of the details. As part of that, we would love to collect more feedback internally and so please help us out by adding feedback and
. We would also love for the Go-to-Market teams to suggest makers who might have valuable input on this feature, and we plan to run additional user tests for other scenarios like coming into a collaborative doc, published doc, etc. Finally, we are considering doing an opt-in beta ahead of launching this in order to collect more feedback from existing users and ease people into the upcoming change.
Ease the transition:
On the day we release the inline toolbar, users will need to switch to a slightly different way of doing things. We plan to help them by providing in-product callouts that educate them about the feature as well as holding the
Command key
to show the toolbar. We would also love to partner with Go-to-Market teams to produce an instructional video we can link to and be ready to provide support as necessary.
Tell the story:
We plan to write a thoughtful blogpost that shares the “why” of the feature with users, similar to the
. This is an important part of being transparent and clear with our makers, as we change a product that they know and love.
Monitor data:
We want to make sure that this feature does not regress any metrics around discoverability of key features or even activation of new makers. We will build a dashboard to review these metrics so that we can investigate and address any issues we find.

af63e3f18a4f24b78d04ec1aa469fb031638b015.gif

As a story team, we believe this feature does not lend well to running an A/B test because it could cause maker content to look different for different collaborators. And, running an A/B test also makes it harder for us to effectively tell the story of this launch and ensure that our essential help articles are up to date. We also believe that there are longer term benefits to making this change (outlined at the top), and are comfortable launching if we do not regress metrics we’ll outline in another writeup and dashboard. However, we are still open to revisiting this decision and would love your input on this.

I’ve read this far
4

How do you feel about this plan?

Dory: questions & discussion topics


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.