How do I review content?#

Contributor: Kenny WJ Chua

Congrats! You have completed a draft of a handbook section. Before committing, please consider the following guidelines on giving and receiving feedback, as well as a checklist of points for self/peer review.

Thanks again for your contributions!

Giving good feedback#

  • Focus on the idea, not the person

  • Follow up with a constructive suggestion

  • Allow the recipient time to react to your feedback

  • Point out the things your like

  • Be polite—provide the feedback that you would appreciate receiving

Receiving and integrating feedback#

  • Feedback is not personal; it is intended to improve the content

  • Go through each reviewer’s comments in turn

  • Acknowledge the reviewer’s help, consider each piece of feedback, and evaluate if you should accept it

  • If you receive contradictory feedback, consider what the reader really needs to know

Review checklist#

Please review your own writing against the following criteria. If there are any deviations, are there strong reasons for them being so?

Technical#

  • Is the text actionable for the reader?

  • Are technical concepts applied in a sound manner?

  • Are there technical concepts/terms that need to be explained to the reader?

  • Is there any jargon that might lead to confusion?

  • Are technical terms used in a consistent manner?

Completeness#

  • Does the text provide adequate (but not necessarily exhaustive) information to address the question in an actionable manner?

  • Are there any gaps/assumptions that ought to be explained?

  • Are there links to relevant resources (if applicable)?

  • Are there any incomplete placeholders in the prose?

Structure#

  • Is the text in continuous prose with paragraphs?

  • Is there a logical flow of ideas?

  • Are there signposts/topic sentences to guide the reader?

Clarity and brevity#

  • Can the text be understood by a new engineer?

  • Is there duplicate or unnecessary information?

  • Are there issues with language (grammer, tone, vocabulary, etc.)?

Reference:

  • Bhatti et al. (2021) Docs for Developers: An Engineer’s Field Guide to Technical Writing. Ch 4. [link]