Editing comments should be constructive, kind, and actionable. If you're asked to review a piece of text, here are my tips for creating a useful comment. Try to cover the what, the what's-up, the why and the what now.
The what
Identify what you're commenting on: word, sentence, section, whatever it may be.
Depending on the tool you’re using, you can usually visually indicate “the what” by highlighting it. If you can’t, you need to spell it out. Use double quote marks to clearly reference what your comment is referring to.
The what’s-up
Articulate what needs to change.
What is the nature of your edit? Does the text need to be corrected, swapped out, moved, supported with evidence? Describe what’s not working. Or does the text need to be celebrated? Describe what’s great about it! Praise helps writers continue good habits.
The why
Explain the why.
It’s crucial to link your edit back to a style guide, a writing principle, a grammar rule, a legal requirement. This keeps your edit objective. The writer is less likely to feel attacked or get defensive if they understand the reason for the suggested change.
Hot Tip: At OSP, we use editing codes to combine the what's-up and the why with one beautiful short code. Check them out!
The what now?
Give practical guidance for next steps. There are a number of ways you can do this:
- Suggest alternative wording in your comment.
- Directly make changes to the text in suggestion mode. Let the author know what you’ve done and why.
- Ask the author to re-write, incorporating your feedback. Be explicit! Avoid vague suggestions like "This needs further explanation".
Example
Image credits
Heart embroidery photo by Magdaline Nicole on Pexels.