Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganise code reviews section #680

Open
wants to merge 11 commits into
base: main
Choose a base branch
from

Conversation

StevenMaude
Copy link
Contributor

@StevenMaude StevenMaude commented Apr 6, 2022

⚠️ 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!

Footnotes

  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.

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?".
@StevenMaude
Copy link
Contributor Author

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?

@madwort
Copy link
Contributor

madwort commented Apr 7, 2022

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.

@StevenMaude
Copy link
Contributor Author

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.

@opensafely opensafely deleted a comment from render bot Aug 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants