docs: add a page on implementing peer reviewer's feedback

[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 #213

[rkratky]

The build is failing because you have not included your new file in any table of contents. See the reported error:

[...]website/library/reference/how-to-implement-peer-reviewer's-feedback.md:
WARNING: document isn't included in any toctree

In other words, the new article would be included in the docs structure. To fix that, add it to the respective index.md file. You added it to the reference directory, so the index.md in the directory would like this:

# Reference

```{toctree}
:maxdepth: 1

resources.md
how-to-implement-peer-reviewer's-feedback.md
```

However, consider the following two things:

• The filenames should not contain special characters (such as an apostrophe) because that can cause problems.
• The content looks more like an 'explanation' than 'reference' to me.

[CBID2]

The build is failing because you have not included your new file in any table of contents. See the reported error:

[...]website/library/reference/how-to-implement-peer-reviewer's-feedback.md:
WARNING: document isn't included in any toctree

In other words, the new article would be included in the docs structure. To fix that, add it to the respective index.md file. You added it to the reference directory, so the index.md in the directory would like this:

# Reference

```{toctree}
:maxdepth: 1

resources.md
how-to-implement-peer-reviewer's-feedback.md
```

However, consider the following two things:

• The filenames should not contain special characters (such as an apostrophe) because that can cause problems.
• The content looks more like an 'explanation' than 'reference' to me.

Hey @rkratky. I implemented the changes and the build still does not work.

[rkratky]

You haven't correctly referenced the file. It needs the exact file name (and nothing else). Please, have a look at the error. (I'm not at my computer now, so I can't fix it for you.)

[rkratky]

The log shows these errors:

[...]website/library/reference/index.md:3:
     WARNING: toctree contains reference to nonexisting document
     'library/reference/How to review someones work <how-to-review-someones-work>  '
[...]website/library/reference/how-to-review-someones-work.md:
     WARNING: document isn't included in any toctree

Note the empty spaces: work> ' -- that confused the parser. Removing those spaces fixes the build:

-How to review someones work <how-to-review-someones-work>  
-How to implement peer reviewers feedback <how-to-implement-peer-reviewers-feedback>
-
+How to review someone's work <how-to-review-someones-work>
+How to implement peer reviewer's feedback <how-to-implement-peer-reviewers-feedback>

(I also added the apostrophes to the article titles. They can be there -- just not in the file names.)

As I mentioned before, I'd also suggest moving the article to the 'explanation' (or 'how-to') category as it doesn't seem to be a 'reference'

[s-makin]

This LGTM :) the build is now working and it looks good!

The spellchecker is complaining about the US spellings, which is the only failure on the automated checks now. Personally, I would prefer contributors to be able to focus on the content and not which version of English they're using - it might be worth us deciding collectively on our approach here. I'm in favour of adding both US and GB English to the spelling checker so that only genuine spelling errors are highlighted, to reduce the mental load for people when they might be wrangling with git etc for the first time. Not every project who signs up to ODA is going to use the same language, so it's better to err on the side of being permissive imo.

Feel free to add the US spellings the spelling checker is complaining about to the spelling exception list so we don't get those errors, and then I can merge. Feel also free to add a new issue to open this up for discussion if you want :)

[CBID2]

This LGTM :) the build is now working and it looks good!

The spellchecker is complaining about the US spellings, which is the only failure on the automated checks now. Personally, I would prefer contributors to be able to focus on the content and not which version of English they're using - it might be worth us deciding collectively on our approach here. I'm in favour of adding both US and GB English to the spelling checker so that only genuine spelling errors are highlighted, to reduce the mental load for people when they might be wrangling with git etc for the first time. Not every project who signs up to ODA is going to use the same language, so it's better to err on the side of being permissive imo.

Feel free to add the US spellings the spelling checker is complaining about to the spelling exception list so we don't get those errors, and then I can merge. Feel also free to add a new issue to open this up for discussion if you want :)

Thanks @s-makin! :) I’m not on my computer at the moment, so I’ll make those changes later. I’ll definitely raise your suggestion as an issue.

[CBID2]

ot every project who signs up to ODA is going to use the same language

Made the changes and the issue @s-makin! :)

[s-makin]

ot every project who signs up to ODA is going to use the same language

Made the changes and the issue @s-makin! :)

Awesome, thanks for that! I see all the other points have been addressed so merging now. Thanks for adding this content, I think it'll be really helpful for aspiring TAs :)