From 38093f5a075c65422d9216b8c3f62a2e367c635c Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Fri, 14 Nov 2025 15:36:20 -0800 Subject: [PATCH 1/2] Add review process overview to review-policy.md --- docs/review-policy.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/review-policy.md b/docs/review-policy.md index 9d61151d2b..d46476dfa8 100644 --- a/docs/review-policy.md +++ b/docs/review-policy.md @@ -1,5 +1,13 @@ Team members are given permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: +## Review Principles + +Reviewers and authors should focus on a few key principles during the review process: + +* **Understandability**: Language within the reference should be understandable to most members of the project. Contributions should assumes that readers are familiar with the rest of the content of the reference, but wherever possible sections should facilitate that understanding by linking to related content that are needed to build an understanding. +* **Defensibility**: When the lang-docs team merges a change to the reference they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the reference. Whenever possible, changes to the reference should back up any claims they make with concise examples verifying their correctness. +* **Voice**: Authors are not expected to have specification writer competence when drafting new contributions to the reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the reference. Team members are expected to bring editorial experience as part of their reviews and will edit the phrasing to fit the reference before merging if necessary. + ## Policy changes - Significant changes to the policy of how the team operates, such as changes to this document, should have agreement of the team without any blocking objections. From 81ed7c1e53ad233b01ef8452026838578c14dd0e Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 18 Nov 2025 22:05:08 +0000 Subject: [PATCH 2/2] Revise "review principles" text This text is great. Jane put this together after talking with the team in some detail in a lang-docs office hours call. In this commit, we revise the wording slightly and adjust capitalization to match our style. --- docs/review-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/review-policy.md b/docs/review-policy.md index d46476dfa8..2195c4440c 100644 --- a/docs/review-policy.md +++ b/docs/review-policy.md @@ -1,12 +1,12 @@ Team members are given permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: -## Review Principles +## Review principles Reviewers and authors should focus on a few key principles during the review process: -* **Understandability**: Language within the reference should be understandable to most members of the project. Contributions should assumes that readers are familiar with the rest of the content of the reference, but wherever possible sections should facilitate that understanding by linking to related content that are needed to build an understanding. -* **Defensibility**: When the lang-docs team merges a change to the reference they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the reference. Whenever possible, changes to the reference should back up any claims they make with concise examples verifying their correctness. -* **Voice**: Authors are not expected to have specification writer competence when drafting new contributions to the reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the reference. Team members are expected to bring editorial experience as part of their reviews and will edit the phrasing to fit the reference before merging if necessary. +* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assumes that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content. +* **Defensibility**: When the lang-docs team merges a change to the Reference, they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the Reference. Whenever possible, changes to the Reference should back up any claims with concise examples to verify correctness. +* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc. to fit the Reference before merging if necessary. ## Policy changes