Conventional Comments at Sendcloud: better feedback
Tags: productivity, writing, feedback
Published: 2021-12-10 13:59:25

_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](https://conventionalcomments.org/) 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](https://gitlab.com/conventionalcomments/conventional-comments-button) 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](https://www.meetup.com/UXify-Eindhoven/events/281406449/), 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!