opensafely
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.
Feedback welcome on this particularly :ear:
I'm as interested in what people think about the overall approach. Does it look like a better structure of this content?
Just had a read through, followed by a look at the existing version. I like it - for me it has that feeling of overly long content that's been usefully refactored into chunks, making it easier to digest. And the Render preview was crucial for reviewing this.
One consideration here would be whether the URLs should be better organised or not. For instance, code-reviews/for-authors and code-reviews/for-reviewers might be better than code-reviews-for-authors and code-reviews-for-reviewers.
We haven't generally given too much thought to URLs, I don't think, but if we can have a good structure from the outset for new pages, that would be good.
Going to close this as it wasn't intended for merge and is now three years old.
