You’re coding all day and now you have to review a how-to article that your colleague has written for the dev portal. Or maybe the tech team lead wants you to review a post for the company blog. If writing is not your happy place, don’t worry - you don’t need to be a good writer to be a good reviewer. You just need to put yourself in the place of the reader, who is probably going to be someone like you.

Reviewing written content is a specific type of task, so take your time to make that context-switch. Here are some straightforward steps to help you review the text of others.

Step 1: Read the whole thing

First, read the whole piece of writing through to the end. This is the easiest bit. Get yourself a cuppa and just read the thing. No matter how tempting it is to mark-up the text now, don’t do it. Stay strong!

Read the content thoroughly before you get into editing mode—Allie Decker

Step 2: Positive feedback

This bit can be hard. You may have developed an eye twitch from step 1 but rise above it and find at least one thing you like about it.

This ‘positivity pass’ packs a powerful punch. Amongst other things, it will:

  • Put you, as the reviewer, in a compassionate headspace.
  • Establish rapport between you and the writer.
  • Reinforce good habits for the writer.

You can do praise at the line level or include it in your feedback summary in step 4.

Tip: Use Conventional Comments and preface your feedback with labels like Correction, Suggestion, and Praise.

Step 3: Corrections, questions, suggestions

Now we get into the meat of the task. This is your longest step.

Always explain why you’re making a change or suggestion. Your language is important—be tactful when making comments.

Corrections

Corrections are for things that are wrong - not according to you, but according to a neutral, external authority.

Your writer probably doesn’t need you to pick up grammar errors - leave that to the Grammarlys and Vales of this world, and focus instead on where your strengths lie. If you’re reviewing a how-to article, actually follow the steps and test it out. If it’s a blog post explaining how a product feature works, bring your smarts and verify the accuracy.

Questions

In your role as reviewer, you advocate for the reader, so question anything that doesn’t make sense to you. When asking a question, think about whether you actually want an answer from the writer or whether you just want to create a thought-provoking prompt.

commentsquestions

Suggestions

Suggestions make up the majority of editing feedback, so here is where you’ll spend most of your review time. The idea is to polish and improve the final written piece.

There are two types of suggestions, depending on how necessary the change is.

  • Recommendations - If these changes aren’t made, the writing is not fit for purpose. Your suggestions will probably be about structure and narrative flow: like re-ordering chunks of text, adding context or reducing word count.

  • Possibilities - If these changes aren’t made, it’s not the end of the world. Your suggestions here are likely to be about word choice, phrasing, and style decisions.

Step 4: Feedback summary

Finally, write a feedback summary. This is a brief statement you include when you pass the document back to the writer - via DM, email or your task management tool of choice.

Summarize your feelings about the written piece, and touch on the type of feedback you’ve given. This is the first thing your writer is going to read from you. Make it kind and use it to manage their expectations.

feedbacksummary.png

Another string to your bow

If all you do is praise one thing, ask one question, and write a brief feedback summary - you’ve added value. It will show the writer that you’ve read and thought about the content.

The ability to peer review someone else’s writing is a great skill to develop. Editing prose is a process that works your analytical, writing, and communication skills—all of which are going to help you be a multi-talented developer.

Further reading

Image credit: Art supply photo by Pixabay on Pexels.