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!
- 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
- 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
Please review your own writing against the following criteria. If there are any deviations, are there strong reasons for them being so?
- 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?
- 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?
- Is the text in continuous prose with paragraphs?
- Is there a logical flow of ideas?
- Are there signposts/topic sentences to guide the reader?
- 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]