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