doc: add a page on how to review someone's work

[CBID2]

Description

This pull request adds a document on peer-reviewing other people's work. Peer reviews are an essential skill in being a technical writer, regardless of experience level, so providing this guide would help people are new to the world of technical writing and be a great refresher for seasoned vets.

Issue

Closes #188

[s-makin]

Hi @CBID2 - thanks for adding this new content to the website! I've had a look at the build failures you're getting, and I think it's related to the problem that this PR solved over the weekend. I don't see any other problems, so if you can incorporate the changes from that PR then the build should pass (I think!)

[s-makin]

Thanks for kicking this off @CBID2 - it's a great start and most of my suggestions are for extensions to it rather than changes. Please feel free to take or leave whatever you want, and I'm happy to bikeshed on anything you want to discuss further.

I do wonder if maybe this wants to be two pages in the end - one for reviewees and one for reviewers, because handling being reviewed is just as important as handling giving reviews, and the former leads directly to the latter. But we can see how it shapes up after others have had a chance to leave their thoughts as well.

[s-makin]

I honestly think that "doing reviews" (from both directions) is the most important skill you can have as a TA. It's the interface between different perspectives, and it's where clarity and quality arise as a natural result of people engaging honestly with the process. When you're a new TA (or a new writer in general), you're definitely going to be getting reviewed way more than you're giving reviews.

In academia (where I started) we have the trope of "reviewer 2"

Reviewer 2 symbolizes the peer reviewer who is rude, vague, smug, committed to pet issues, theories, and methodologies, and unwilling to treat the authors as peers.

Getting a bad review is a pretty universal experience, and it's important not to take a bad review personally - so I think it would be pretty valuable in this article to have some discussion about being reviewed as well. Specifically:

• How to approach being reviewed (how to not take it personally, even if the review feels bad)
• Extracting useful feedback from a review
• Developing your judgement around which feedback to accept and where to push back

(This could also be on a separate guide I guess?)

[s-makin]

I can't speak for everyone, but I personally don't tend to differentiate between any of the different types of reviews that I do. The skills involved are the same, no matter what we call it. It might be good to provide (here or thereabouts) what things to focus on and in what order when you're reviewing. Maybe even a checklist ordered by priority?

For example, my mental checklist when I'm reviewing is broadly:

1. Overall structure & flow

• Are the steps in the correct order
• Will the reader be able to make logical sense of it (even if they don't know the topic)
• Have all jargon terms been defined at the first use

2. Accuracy & completeness

• Given the correct ordering, are all the steps accurate
• Do the code snippets do what the doc says they do
• Are there any steps missing that need explaining?
• If you run through the doc from start to finish, does it work?

3. Wording & clarity

• Is everything well worded
• Are there any unclear bits?
• Can anything be made shorter
• Does the tone suit the message?

4. Nits

• Spelling and grammar
• Formatting
• etc

It might worth crowdsourcing such a list, if anyone else wants to add their $0.02 (so it's not just one of my chaotic braindumps lol).

I often do several passes at a single document to make sure that I'm capturing all these things and not trying to focus on too many things at once. I don't tend to worry about the nits until I'm happy with everything else, because otherwise you end up repeating effort.

[s-makin]

I have seen people doing this before but I don't know if there's a particular standard they're following. If you know of one, it would be helpful to suggest a list of recommended categories or a link to the standard.

[s-makin]

For practicality, I always like to have a rendered version of the doc next to the code when I'm reviewing - it's a lot easier to spot spelling and formatting problems, and to check if links are working. At least on GH that's easy if you have the readthedocs PR preview activated, but if not, you can run the branch locally - I think we have a page on that in the getting started guide, if you wanted to link to it.

[s-makin]

Suggested change

- **Be objective as much as possible:** Behind every piece of documentation is a person, so it's crucial to be mindful of your wording and tone when giving feedback. For example, if you noticed that a section is missing a code snippet or a key detail about the product, it would be ineffective to say, "This section stinks." Consider pointing out the strengths of the work and the areas that could be improved. For example, "this section describes the steps effectively, but the screenshots are missing alt text."

- **Be objective:** Behind every piece of documentation is a person, so it's crucial to be mindful of your wording and tone when giving feedback. For example, if you noticed that a section is missing a code snippet or a key detail about the product, it would be ineffective to say, "This section stinks." Consider pointing out the strengths of the work and the areas that could be improved. For example, "this section describes the steps effectively, but the screenshots are missing alt text."

[s-makin]

In addition to the other points you mentioned here, I think it's also critical to be mindful about what is really personal preference vs objective improvements. For example, I really super love the Oxford comma, and I will put it in whenever I think I can get away with it, but I would never try to enforce someone else doing it because it's really my own preference. I just have to get over my annoyance when people don't use it 😂

[s-makin]

I know it's the scientist in me, but I always believe in going ultra specific. I don't just say "this section is missing a code snippet", but rather "this section needs a code snippet on X and the corresponding output". I find that people often give me precisely what I ask them for, to the actual letter, so I have found that the best way to avoid multiple rounds of reviews is to be ultra specific about what I want to see.

[s-makin]

I cautiously agree with this, but with the caveat that concise != short.

Being concise means giving all of the information needed in the shortest possible manner. I think organising your feedback so that it's consumable is a much more helpful way to provide it. So I'd advocate for renaming this point to "be helpful".

The thing I always try to remember when I'm reviewing is that just as I don't know what the reader of my documentation already knows/doesn't know, I also don't know what the person I'm reviewing may or may not already know. I think it's fine to add context and other important information to help the "reviewee" (yeah, that's not a word) understand the reason why I'm asking for something.

When I was first starting out as a writer, when I understood the reason why something I'd done was "wrong", I was able to make sure I didn't make the same mistake again. It can be challenging to be reviewed and get a lot of feedback, but it ultimately makes you a much better writer if you can take it on board.

[s-makin]

I'd also add an extra point at the end; something like "don't endlessly nitpick" or "don't be mad if it's not 100% how you would have done it". Maybe "be flexible" if we wanted to phrase it a bit more kindly.

The end goal of reviewing is to make sure that the work is a) correct/accurate, and b) the best version of itself (for now). The nature of online documentation is that it's 100% going to change at some point, so there's no point gatekeeping over stupid nits. I've seen maintainers insist that their way is the only way, and PRs end up stuck in a weird limbo where it takes like 6 months to get them landed (if they don't get abandoned) just because they can't agree with each other. Usually they say "no not like this" but also don't say what they want instead. Usually over several rounds. Usually also changing their minds halfway after several rounds of bikeshedding. I guess my point is that we should advocate for people to "don't be that guy".