Reorganise code reviews section#680
Conversation
This is using the Diátaxis approaches of: * picking some documentation arbitrarily and trying to make small improvements * keeping different categories of documentation separate As written, this felt like a mixture of explanation and how-to guide, so split these out into two different pages.
* Simplify some of the text. * Explicitly explain what authors and reviewers can gain from code reviews. * Use semantic line breaks.
* Complete some incomplete thoughts. * Reword a few sentences. * Use more semantic line breaks in edited content.
As it seemed more "about code review" than "how to do a code review".
The page no longer really discusses using code reviews, but solely what they are.
The "when to ask for code review?" logically should be ahead of the "how?".
Feedback welcome on this particularly 👂 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, 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. |
review documentation, applying the
Diátaxis framework.
It's not necessarily that we want to merge this.
This PR:
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!
Footnotes
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. ↩