Document comments have become a key element of how we give and receive feedback from colleagues, but have you ever stopped to think about your approach?
In the world of distributed work, live documents and comments have become key to how software engineers collaborate at work. But poor comments etiquette can negatively impact colleagues, hamper collaboration, and complicate important decision making.
Good comments etiquette should follow the same principles of collaborating effectively offline, such as:
- Listen fully and presently
- Confirm alignment and understanding
- Collect your thoughts before responding
- Provide actionable feedback
- Agree on next steps
These key principles don’t change in a collaborative doc. They are just applied differently.
Why care about comments etiquette, anyway?
As humans, the more we do something, the more we go on auto-pilot. Because reviewing docs is part of our everyday life, we may let certain habits slip, like jumping to conclusions before reading an entire doc, or providing hasty comments that could muddy the waters more than clarify them.
How to get high quality feedback on your doc
The quality of feedback you receive is partially in your own hands. Setting an example for your teammates and clear expectations in your doc can make all the difference.
Be specific on the type of feedback you’re looking for
When asking for feedback on a document, it’s important to clarify what you’re looking for. For example, docs for early-stage project brainstorming may need strategic, directional level feedback. Whereas docs that are near the end of a project may only need an edit and a proof read. Make sure to specify this when sharing.
You should also communicate if you just need feedback in a portion of the doc. The person you’re requesting feedback from may be a subject matter expert on only one section of the contents. Or, they may not have the context necessary to provide feedback in other sections. Clarify by saying things like:
- “I’d like your feedback on the database schema” or,
- “I’d like your feedback on this section of the blog draft”
Avoid too many cooks in the kitchen. If portions of the doc have already been reviewed and agreed-upon, more reviews are unlikely to reveal new insights. Your time is better spent in other parts of the document.
Set a timeline
Everyone in your organization is managing their own deadlines. To help your reviewers prioritize your doc against their other work, provide a clear timeline for when you need feedback submitted by.
A simple note like, “Would love your comments by 9am the morning of the meeting, so I can review them before we discuss as a group,” can help provide context for why you need feedback by a certain time.
Create expectations for how you’d like your work reviewed
Not everyone is great at providing feedback. You may need to provide them direct instructions on how you’d like them to approach reviewing your doc. Will Larson, CTO at Carta, in his article on discouraging perfect documents, underscores the importance of telling your reviewers the workflow you’d like them to follow.
Don’t be afraid to be prescriptive and assertive with how you’d like your work reviewed. As Larson writes, “If you ask someone to edit a document, a surprising number of folks will immediately gravitate to tweaking words or providing grammatical feedback. Sometimes this is useful, but it usually isn’t.”
Consider if feedback is better in public or private
Some feedback you might not want to be viewed by other people. One way I like to manage this is by creating copies of the doc and adding the person’s name to the title. This makes it easy to see which doc has been shared with each person. Just be sure to keep your versions organized. After you’ve collected the feedback, you can combine them into one doc.
Organize and triage comments
After you’ve received feedback, work your way through them methodically. Always keep an open mind when it comes to feedback. “Just be careful not to fall in love with what you’ve written until after you’ve reviewed it with others,” Larson writes. You don’t have to respond and make changes to your doc immediately. Take time to think.
If you need to ask questions to clarify a piece of feedback, start there. Don’t begin implementing changes until you’re crystal clear on the meaning and intent behind the feedback. If you opt not to implement feedback, provide a thoughtful response on why you’ve chosen the direction you did.
For actionable feedback, it can help to respond to comments with an emoji to signal you’ve received (:eyes:), or implemented it (:white_check_mark). Don’t resolve or dismiss comments that may offer important context to people reviewing the doc in the future.
Comments that provide tactical-level feedback that doesn’t pertain to the actual take-aways of the document can more safely be resolved, such as grammar changes, adding links to sources, or minor additions to add clarity.
Know when to take things offline
Comments are a powerful tool, but they can’t completely replace the need for in-person conversations. It’s easy for written words to get lost in translation. Especially if it’s a passionate or opinionated discussion.
A general rule is: If you need more than three comments back and forth to discuss, you should probably move to a face-to-face conversation, like a Slack huddle or Zoom call. Make sure you circle back on the initial thread and document a summary of what was discussed during that call for future reviewers.
How to provide clear, actionable feedback in docs
More like this
Taking the time to slow down and think about what feedback you provide and how you provide it, will make you a better collaborator and help uplevel your entire team.
Follow an intentional comments workflow
Avoid jumping straight into a doc and going on a commenting blitz. Here’s the comments workflow I would recommend:
- Put the doc in read-only mode.
- Read the doc in its entirety, taking notes on the side as you go through.
- Once you’ve finished reading the doc, write a summary of your high-level feedback in a comment near the top.
- Then, work your way back through the doc and provide section-specific feedback.
This workflow will help ensure you don’t ask questions that become clear later in the document and your comments are made with full context of the doc’s contents.
As mentioned in Jenny Karn’s article, Mastering the etiquette of Google Docs, “a good comment:
- Is succinct. No one wants to read an essay.
- Is actionable. Ask a direct question or offer a specific edit, but don’t leave open-ended statements or opinions that are difficult for others to act upon.
- Tags appropriate team members by name so they know to look it over.”
Remove opportunity for bias
To avoid being swayed by other reviewers’ feedback, don’t read other comments before you’ve completed your initial read-through. This will ensure your point of view is completely your own before you start considering others’ thoughts.
Make sure what you’re referencing is clear
If you’re making a comment on a large section of the document, avoid highlighting the entire section. This might seem counterintuitive, but highlighted text for a comment in docs can make it difficult to review visually. What’s better is to highlight just the beginning of the section and make the scope of your feedback clear in your written comment.
You can also consider using quotes/block quotes within the comment text to specify which text you’re referring to. To do so, use the Markdown syntax for block quote, which is “>” followed by a space.
Understand when your feedback might not belong in a comment
Comments aren’t always the best tool for providing feedback. You might want to consider a more synchronous approach if the following are true:
- You need to provide sensitive feedback you think should be delivered privately.
- You believe your feedback may get lost in translation.
- It’s going to take more than three comments back and forth to resolve.
- You’re very unclear on a point and need to talk it through.
Let your colleague know you’ve provided feedback
Messy email threads of comments and suggestions can be hard to sift through. To ensure your comments don’t get lost in the mix, send a quick ping to your teammate to let them know you’ve completed that round of feedback. If your colleague responds to your comments, do your best to respond promptly. Or, use an emoji to indicate that you’ve seen their response.
Good review and comments etiquette makes all the difference when it comes to collaborating effectively. Don’t let good habits fall by the wayside. Even if your team doesn’t use these guidelines, be the person to spearhead this change in your organization.
