In From code reviews to prose reviews, I describe a 4-step process for doing a review. Three of those steps involve writing! Here I want to dig deeper into each of those bits of writing:

  • Corrections
  • Suggestions
  • Questions
  • Praise
  • Commentary

Corrections ❌

The word “corrected” implies a value judgment - a rightness or wrongness. Is the thing you noticed actually wrong? Now is not the time to be subjective. A neutral, external authority should support these types of edits.

Corrections are usually about:

  • Grammar and punctuation
  • Adherence to a style guide
  • Facts or evidence to support a claim
  • Technical accuracy

It’s good to explain why something needs to be corrected. In your feedback, link back to the external authority (a style guide, legislation, evidence) to de-personalize your correction and make it feel less judgemental to the writer.

Signposting corrections 💬

How does the writer know it’s a correction?

  • In Google Docs or MS Word, work in suggestion mode so the author gets a visual cue in the UI.
  • If you’re working in text, you can preface your feedback with the label correction (see https://conventionalcomments.org/).

Suggestions 💡

Isn’t everything a suggestion?🤷‍♀️ I think there is room for nuance here, between strong suggestions (recommendations) and take-it-or-leave-it optional suggestions (possibilities).

  • Recommendations - These are strong suggestions because if the changes aren’t made, the writing won’t be fit for purpose. Welcome to the basis of editing. You’re looking to improve and polish the written piece. Your feedback should seek to elevate.

    Your recommendations shouldn’t be based on personal preference, but rather, on writing guidelines, reader advocacy and an understanding of broader context.

    Of course, the writer can still opt to reject your strong suggestions. Rejection hurts, and it’s up to you to continue a back-and-forth convo if you feel it’s warranted. Sometimes you have to let it go.

  • Possibilities - Optional but recommended suggestions. If these changes aren’t made, it’s not the end of the world. The writing still works - it just might not hit all the notes.

    Unlike recommendations, these types of suggestions tend more toward subjectivity. Your personal experience with inclusive language, localization, phrasing, and presentation choices is authentic and valuable to the writer.

Signposting corrections 💬

How does the writer know the difference between a strong suggestion and an optional suggestion? The language you use in your edit, and the amount of feedback and explanation you provide. Stronger suggestions can be worded from the point of view of the reader. I would frame most optional suggestions as questions.

Questions ❓

It’s not all corrections and suggestions. Asking questions shows the writer respect—you are a humble (not omniscient) editor.

Three ways to use questions:

  • Ask a genuine question. “Has this feature been released? I thought it didn’t make it in.”

  • Prompt the writer to see with fresh eyes. “What do you mean by this? It’s not clear. Let’s add another sentence to clarify the point.”

  • Frame a suggestion. “Is the order important? Let’s move this bullet point to the top because it seems to carry the most weight.”

Don’t ask questions to be lazy—here is your opportunity to add value as an editor. Check the spelling, follow the link, find the website, confirm the product name. Reviewing is not a passive task.

Signposting questions 💬

How does the writer know it’s a question? Trick question - use a question mark! 😁

Be clear whether you actually want to enter into a conversation (sync or async), or if this question is just a thought-provoking prompt. If you do want to have a conversation, commit to several more rounds of sync or async convo after handing over the task. Be there for your writer.

Praise 💜

Praise as a form of feedback is about helping someone continue to do a good thing. Don’t hold back on praise.

Read more about praise:

Signposting praise 💬

How does the writer know it’s praise?

Commentary 📝

Commentary is a broader kind of feedback in the form of a statement. Think of this as your big picture wrap-up. It doesn’t have to be long - but it can be if you want.

It can include:

  • Your general impression of the written piece
  • Suggestions for further research to add more detail
  • Notes on broader context and content strategy
  • Broad brushstrokes praise
  • Comments on style decisions
  • Notes for things to remember on publish

Rather than do line-level editing, you might choose to only write a commentary. This might be if the piece is mostly very good (or very bad).

Signposting commentary 💬

How does the writer know that this feedback is commentary? It’s at the very top or start of the document, or it’s included when you hand the writing back to the author via email or DM.

Further reading

Image credit: Chewed pencil photo by Kim Gorga on Unsplash