How do I review content?
Contents
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]