The polite doc: Etiquette for the modern workplace
Copy doc
Sign in
The polite doc: Etiquette for the modern workplace
Make your doc a kinder, more convenient space for collaboration.
Back when we were in the same office, we opened doors, put our coffee cups in the dishwasher, and knew not to interrupt someone with headphones in. And so much of that politeness relied on tone, body language, and facial expressions—intricate social and cultural norms that are attached to everything we do, work included.

Now the place we spend nearly
isn’t an office, it’s a suite of digital work tools. Including Coda docs.

So we asked a few willing Codans about how politeness (or lack thereof) looks and feels in their docs. Their answers, which you can read below, paint a clear picture of dedication to creating new norms that fit Coda’s specific culture of collaboration.

Take our survey as we explore a new frontier for politeness—we’d love to see what’s true of your experience and team’s culture.

Here’s the first question:

What does is mean to be polite in a doc?
Add your answer.

Doc making is an act of care.

Politeness norms in a virtual space are understandably ambiguous. Because the
are no longer in play, seemingly every choice becomes important. Like how to avoid conflict and be inclusive. Or how to compensate for lack of visual and verbal cues.

For Coda, in-doc politeness goes beyond superficial friendliness and signals a deeper consideration—respect from both the doc makers and the doc editors.

A polite doc maker takes care to present their information in an easy-to-consume way for their readers. A polite doc user takes care to leave comments that are unobtrusive and constructive for the creator.

With mutual agreement, Codans—both doc makers and editors—make sure the other has everything they need to succeed. Whether that’s ensuring feedback we leave is actually constructive or keeping in mind who else might see the comment, we communicate care for each other, everyone’s time, and the doc itself.

I treat a collaborative doc as I would a meeting with the same number of attendees. If I wouldn’t say it out loud in front of everyone in that context, I don’t say it in the doc comments.

And without that agreement, our collaborations aren’t quite as seamless.

So, what does impoliteness look like to you?

What does is mean to be impolite in a doc?
Add your answer.
When do you collaborate on a teammate’s doc without asking, including making in-line edits, adding tables, changing views?
Add your answer.

Impoliteness isn’t about
what
, but
how
.

Like politeness, impoliteness is subjective; you just know what feels rude—in a doc or otherwise. For Codans, impoliteness isn’t always about the what, but the how.

Especially for docs that are likely to have multiple collaborators, impoliteness is roasting the author, sharing overly critical feedback without context, or not clarifying when something is an insight or an opinion.

Although comments provide the most obvious opportunity to be rude, we heard that impoliteness isn’t constrained to verbal feedback. Making in-line edits, changing or removing a table, or altering the doc’s structure without permission were all pain points voiced in our survey. And it’s no surprise that these actions don’t foster meaningful collaboration for us.

There should be a mutual understanding of collaboration and potential for these edits. Otherwise, I’d ask. I’d only make changes without asking under urgent circumstances.

Because collaboration is such a vital piece of Coda’s culture, we want doc editors to feel welcome suggesting edits, even if that means altering the structure of the doc. Many of us find giving doc editors space to play with the doc—usually by creating scratch pages—provides an out-of-the-way place to work without stepping on anyone’s toes.

Feedback on feedback.

Instead of blindly sharing docs, we try to approach doc sharing like leading a meeting, with thought and intention. The added context and expectation setting often provides the clarity needed to make sure doc makers and editors both get what they need.

For Codans, the moment a doc maker shares their doc is the best time to tell others how they’d like feedback and when. We also tend to fall back on one of our meeting rituals—a topic voting table—to invite folks to weigh-in and add questions.

I like for people to share their “why.” Why are you asking this? Where is your opinion coming from? I also like when people ask questions first.

And when we’re in an editing role, we’re inclined to be thoughtful and understanding of the medium. We ask ourselves, “Is this the right kind of comment for the entire team or company to see?”

Beyond the feedback itself, our survey results voiced the need for consideration around the conversational elements of comments. For example, if we want someone to reply to a comment, how many @ mentions are too many before it’s necessary to jump to another channel, like Slack?

If the first @mention doesn’t work, does re-@mentioning read like, “I must be extra-communicative to compensate for your inattention?” Does a Slack DM about one measly comment feel uppity?

And when that person finally pops in to reply, who can close the thread? The doc maker? The person who left the comment in the first place? Some of us are relatively generous:

Hopefully the original commenter will acknowledge and either update their comment if there’s more to do, or resolve the comment if it’s all clear. If they haven’t within 24 hours, I may just resolve the comment myself depending on timeliness and need to de-clutter the reading surface for additional reviews.

Others are not:

I resolve the thread.

Care to share your feedback on feedback?

How do you prefer to receive critical feedback in a comment?
Add your answer.
You need someone to reply to a comment in your doc. What do you do?
Add your answer.
You replied to someone’s comment. Who resolves the thread, and when?
Add your answer.

And a few final questions...

What does the 🙃 emoji mean to you?
Add your answer.
What other doc-specific behavior is particularly rude or polite?
Add your answer.

We’re trying to create a convenient doc.

From our own experiences and Coda culture, being polite in a doc means making and sharing a doc that invites inclusive and convenient collaboration. While politeness can be communicated with words and with actions (or perhaps inactions), we’re in agreement that taking the extra care of being considerate doc makers and editors positively impacts the success of the collaboration.

Of course, this data is only a snapshot of the broader politeness frontier—we can’t wait to read about your own experiences. Head over to
to see more answers from Codans, including what they think of the 🙃 emoji.

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.