documentation
documentation copied to clipboard
Reorganise code reviews section
:warning: This PR is a proof-of-concept attempt to reorganise the code review documentation, applying the Diátaxis framework.
It's not necessarily that we want to merge this.
This PR:
- breaks out the mixture of content from explanation and how-to.
- does some small rewriting, editing and tidying of content [^1]
- favours semantic line breaks (this is not part of the framework)
It is not entirely clear whether the "how" here follows the same structure as a more strict how-to guide. Some of the content here is more advice and guidelines rather than a more definite process. However, nor are the "how-to" guides modified here might not be "explanations" under the framework: are they really theoretical knowledge for study? Maybe!
[^1]: This was via making small improvements where they became apparent or where I saw them. This is as opposed to an extensive rewrite of the entire content end-to-end.