Rob van Gansewinkel, Senior Front-end Developer at Sendcloud
We’re all familiar with the problem: it is easy to misinterpret written feedback. Written feedback lacks information that’s encapsulated in (non-)verbal communication, like tone of voice. Also, in written feedback missing the intent behind a comment is commonplace, when you’re not being explicit (enough).
About 1.5 years ago, a colleague within the frontend chapter shared a link to the Conventional Comments project. After review, this seemed like a possible solution for what we experienced, even more so while working from home.
Conventional Comments can be used in any kind of review or feedback process, including (but certainly not limited to) code reviews. It adds intent and importance to the comment, promising shorter lead times in a review/feedback process.
Using Conventional Comments
The standardized format contains a mandatory “label” and “subject”, as well as an optional “decoration” and “discussion”:
Format:
<label>([decoration]): <subject>
[discussion]
The different label types include:
- praise: highlight something sincerely positive
- nitpick: small, trivial, but necessary changes
- suggestion: propose improvements to the current subject
- issue: highlight specific problems
- question: to address a potential concern (relevancy uncertain)
- thought: represent an idea that popped up from reviewing
- chore: simple tasks that must be done before the subject can be accepted
Example
Imagine you looked at a colleague’s draft for a customer newsletter, and you think they took some liberties describing a product feature. Before hammering away on your keyboard, consider the following:
Bad:
This is not worded correctly.
Better:
suggestion: This is not worded correctly.
Or:
nitpick (non-blocking): This is not worded correctly.
Best:
suggestion: This is not worded correctly.
Can we change this to match the wording of the marketing page?
You’ll find that the third iteration helps you as the reviewer to provide clear & actionable feedback, limits the chance of startling the receiver, and results in shorter lead times in the overall feedback process.
Check out the project’s documentation for more guidance.
Feedback at Sendcloud
With some other enthusiasts in the Frontend chapter we decided to give it a go. While at first it may feel artificial - and you’ll find yourself editing messages you already sent to apply the standard - it helps you focus on the content of your message. It helps guide your writing.
Adoption was a gradual process within the frontend discipline but it is fully embraced by now. I used a Chrome extension for a while to remind myself to use the standard, but eventually it became so natural that I didn't need it anymore. Writing the Conventional Comments way quickly became a habit. You almost prefix your questions in one-to-one, non-digital communication as well!
Half a year ago we introduced the idea to our colleagues within the backend discipline, and they’re gradually adopting it. The UX team started 2 months ago, and they are enthusiastic users. I presented the project at the November 4 Uxify meetup, which we hosted at our Eindhoven office.
We noticed that it’s easier to ask for reviews when everyone works in the same format. Adopting Conventional Comments has benefitted cross-discipline, and cross-team collaboration at Sendcloud. I would recommend anyone to try it out for themselves!
praise: Thanks for reading this article!
Top comments (0)