documentation icon indicating copy to clipboard operation
documentation copied to clipboard

Reorganise code reviews section

Open StevenMaude opened this issue 2 years ago • 3 comments

: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.

StevenMaude avatar Apr 06 '22 17:04 StevenMaude