Clarifying Docs contributor roles (#958)

* Clarifying Docs contributing roles * Clarifying how contributors become members/approvers * Add docs-reviewers alias * Add gyliu513 as docs reviewer * Update DOCS-CONTRIBUTING.md * Update DOCS-CONTRIBUTING.md * Apply suggestions from code review Co-Authored-By: samodell <31352624+samodell@users.noreply.github.com> * Applying comments from DOCS-CONTRIBUTING.md The text in DOCS-CONTRIBUTING was pulled from ROLES, so I'm making the same changes here as I did there. * Update DOCS-CONTRIBUTING.md * Update DOCS-CONTRIBUTING.md
2019-03-13 19:12:45 -07:00 · 2019-03-13 19:12:45 -07:00 · 3f7a02ec80
parent e095752269
commit 3f7a02ec80
4 changed files with 179 additions and 57 deletions
--- a/3
+++ b/3
@ -4,4 +4,5 @@ approvers:
 - eng-approvers
 - docs-approvers
 reviewers:
- docs-approvers
+- docs-approvers
+- docs-reviewers
--- a/4
+++ b/4
@ -9,4 +9,6 @@ aliases:
  docs-approvers:
  - carieshmarie
  - samodell
-  - richieescarez
+  - richieescarez
+  docs-reviewers:
+  - gyliu513
--- a/community/DOCS-CONTRIBUTING.md
+++ b/community/DOCS-CONTRIBUTING.md
@ -1,5 +1,9 @@
 # Contributing to the Knative Documentation

+- [Before you begin](#before-you-begin)
+- [Contributing to the documentation](#contributing-to-the-documentation)
+- [Docs contributor roles](#docs-contributor-roles)
+
 **First off, thanks for taking the time to contribute!**

 The following are guidelines for contributing to the Knative documentation.
@ -20,7 +24,9 @@ Knative documentation follows the
 [Google Developer Documentation Style Guide](https://developers.google.com/style/);
 use it as a reference for writing style questions.

-## Reporting documentation issues
+## Contributing to the documentation
+
+### Reporting documentation issues

 Knative uses Github issues to track documentation issues and requests. If you
 see a problem with the documentation, submit an issue using the following steps:
@ -42,7 +48,6 @@ Note that code issues should be filed against the
 [individual Knative repositories](http://github.com/knative), while
 documentation issues should go in the `docs` repository.

-## Contributing to the documentation

 ### Working group

@ -98,3 +103,122 @@ Code samples follow a similar strategy, where most code samples should be
 located in the `docs` repository. If there are code samples used for testing
 that are only expected to be used by contributors, those samples are put in the
 `samples` folder within the component repo.
+
+## Docs contributor roles
+
+Because contributing to the documentation requires a different skill set than
+contributing to the Knative code base, we've defined the roles of
+documentation contributors seperately from the roles of code contributors.
+
+If you're looking for code contributor roles, see [ROLES](./ROLES.md).
+
+### Member
+
+Established contributor to the Knative docs.
+
+Members are continuously active contributors in the community. They can have
+issues and PRs assigned to them, might participate in working group meetings, and
+pre-submit tests are automatically run for their PRs. Members are expected to
+remain active contributors to the Knative documentation.
+
+All members are encouraged to help with PR reviews, although each PR
+must be reviewed by an official [Approver](#approver). In their review,
+members should be looking for technical correctness of the documentation,
+adherence to the [style guide](https://developers.google.com/style/), good spelling and grammar (writing quality),
+intuitive organization, and strong documentation usability. Members should be
+proficient in at least one of these review areas.
+
+### Requirements
+
+- Has made multiple contributions to the project or community. Contributions might
+  include, but are not limited to:
+
+  - Authoring and reviewing PRs on GitHub in the Docs or Website repos.
+
+  - Filing and commenting on issues on GitHub.
+
+  - Contributing to working group or community discussions.
+
+- Subscribed to
+  [knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev).
+
+- Actively contributing to 1 or more areas.
+
+- Sponsored by 1 approver.
+
+  - Done by adding GitHub user to Knative organization.
+
+### Responsibilities and privileges
+
+- Responsive to issues and PRs assigned to them.
+
+- Active owner of documents they have contributed (unless ownership is explicitly
+  transferred).
+  
+  - Addresses bugs or issues in their documentation in a timely manner.
+  
+### Becoming a member
+
+First, reach out to an approver and ask them to sponsor you so that you can become a member.
+The easiest way to do this is using Slack.
+
+If they are supportive of your membership, your sponsor will reach out to the Knative Steering
+committee to ask that you be added as a member of the Knative org. 
+
+Once your sponsor notifies you that you've been added to the Knative org,
+open a PR to add yourself as a docs-reviewer in the
+[OWNERS_ALIASES](../OWNERS_ALIASES) file.
+  
+## Approver
+
+Docs approvers are able to both review and approve documentation contributions.
+While documentation review is focused on writing quality and correctness,
+approval is focused on holistic acceptance of a contribution including:
+long-term maintainability, adhering to style guide conventions, overall information
+architecture, and usability from an engineering standpoint. Docs approvers will
+enlist help from engineers for reviewing code-heavy contributions to the Docs repo.
+
+### Requirements
+
+- Reviewer of the Docs repo for at least 3 months.
+  
+  - Proficient in reviewing all aspects of writing quality, including grammar and
+    spelling, adherence to style guide conventions, organization, and usability.
+    Can coach newer writers to improve their contributions in these areas.
+  
+- Primary reviewer for at least 10 substantial PRs to the docs, showing substantial
+  ability to coach for writing development.
+
+- Reviewed or merged at least 30 PRs to the docs.
+
+- Nominated by an area lead (with no objections from other leads).
+
+  - Done through PR to update an OWNERS file.
+
+### Responsibilities and privileges
+
+- Responsible for documentation quality control via PR reviews.
+
+  - Focus on long-term maintainability, adhering to style
+    guide conventions, overall information architecture, and usability from
+    an engineering standpoint.
+
+- Expected to be responsive to review requests as per
+  [community expectations](REVIEWING.md).
+
+- Mentor members and contributors to improve their writing.
+
+- Might approve documentation contributions for acceptance, but will ask for
+  engineering review for code-heavy contributions.
+
+### Becoming an approver
+
+If you want to become an approver, make your goal clear to the current
+Knative Docs approvers, either by contacting them in Slack or announcing
+your intention to become an approver at a meeting of the Documentation
+Working Group.
+
+Once you feel you meet the criteria, you can ask one of the current
+approvers to nominate you to become an approver. If all existing
+approvers agree that you meet the criteria open a PR to add yourself
+as a docs-approver in the [OWNERS_ALIASES](../OWNERS_ALIASES) file.
--- a/community/ROLES.md
+++ b/community/ROLES.md
@ -1,6 +1,6 @@
 # Knative Community Roles

-This document describes the set of roles individuals may have within the Knative
+This document describes the set of roles individuals might have within the Knative
 community, the requirements of each role, and the privileges that each role
 grants.

@ -104,7 +104,7 @@ table describes:

 ## Collaborator

-Individuals may be added as an outside collaborator (with READ access) to a repo
+Individuals can be added as an outside collaborator (with READ access) to a repo
 in the Knative GitHub organization without becoming a member. This role allows
 them to be assigned issues and PRs until they become a member, but will not
 allow tests to be run against their PRs automatically nor allow them to interact
@ -113,11 +113,10 @@ with the PR bot.
 ### Requirements

 - Working on some contribution to the project that would benefit from the
-  ability to have PRs or Issues to be assigned to the contributor
+  ability to have PRs or Issues to be assigned to the contributor.

 - Join [knative-users@](https://groups.google.com/forum/#!forum/knative-users)
-  unrestricted join permissions; this grants read access to documents in the
-  Team Drive
+  , which grants read access to documents in the Team Drive.

 ## Member

@ -126,7 +125,7 @@ principles in this document, familiarity with project organization, roles,
 policies, procedures, conventions, etc., and technical and/or writing ability.

 Members are continuously active contributors in the community. They can have
-issues and PRs assigned to them, may participate in working group meetings, and
+issues and PRs assigned to them, participate in working group meetings, and
 pre-submit tests are automatically run for their PRs. Members are expected to
 remain active contributors to the community.

@ -134,41 +133,41 @@ All members are encouraged to help with the code review burden, although each PR
 must be reviewed by an official [Approver](#approver).

 When reviewing, members should focus on code quality and correctness, including
-testing and factoring. Members may also review for more holistic issues, but
+testing and factoring. Members might also review for more holistic issues, but
 this is not a requirement.

 ### Requirements

- Has made multiple contributions to the project or community. Contributions may
+- Has made multiple contributions to the project or community. Contributions might
  include, but are not limited to:

-  - Authoring or reviewing PRs on GitHub
+  - Authoring and reviewing PRs on GitHub.

-  - Filing or commenting on issues on GitHub
+  - Filing and commenting on issues on GitHub.

-  - Contributing to working group or community discussions
+  - Contributing to working group or community discussions.

 - Subscribed to
-  [knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev)
+  [knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev).

 - Actively contributing to 1 or more areas.

 - Sponsored by 1 approver.

-  - Done by adding GitHub user to Knative organization
+  - Done by adding GitHub user to Knative organization.

 ### Responsibilities and privileges

- Responsive to issues and PRs assigned to them
+- Responsive to issues and PRs assigned to them.

 - Active owner of code they have contributed (unless ownership is explicitly
-  transferred)
+  transferred).

-  - Code is well tested
+  - Code is well tested.

-  - Tests consistently pass
+  - Tests consistently pass.

-  - Addresses bugs or issues discovered after code is accepted
+  - Addresses bugs or issues discovered after code is accepted.

 Members who frequently contribute code are expected to proactively perform code
 reviews and work towards becoming an approver for the area that they are active
@ -188,9 +187,9 @@ status is scoped to a part of the codebase.
 The following apply to the part of the codebase for which one would be an
 approver in an OWNERS file:

- Reviewer of the codebase for at least 3 months or 50% of project lifetime,
-  whichever is shorter
+- Reviewer of the codebase for at least 3 months.

+- Primary reviewer for at least 10 substantial PRs to the codebase.
  - One path for getting the necessary reviews is to add yourself to the
    `reviewers` section of the OWNERS file. Note that this does not give
    you any additional privileges. By having yourself listed in this
@ -199,36 +198,32 @@ approver in an OWNERS file:
    discretion of an approver after enough evidence of quality
    contributions.

- Primary reviewer for at least 10 substantial PRs to the codebase
+- Reviewed or merged at least 30 PRs to the codebase.

- Reviewed or merged at least 30 PRs to the codebase
+- Nominated by an area lead (with no objections from other leads).

- Nominated by an area lead
-
-  - With no objections from other leads
-
-  - Done through PR to update an OWNERS file
+  - Done through PR to update an OWNERS file.

 ### Responsibilities and privileges

 The following apply to the part of the codebase for which one would be an
 approver in an OWNERS file:

- Approver status may be a precondition to accepting large code contributions
+- Approver status can be a precondition to accepting large code contributions.

- Demonstrate sound technical judgement
+- Demonstrate sound technical judgement.

- Responsible for project quality control via [code reviews](REVIEWING.md)
+- Responsible for project quality control via [code reviews](REVIEWING.md).

  - Focus on holistic acceptance of contribution such as dependencies with other
-    features, backward / forward compatibility, API and flag definitions, etc
+    features, backward / forward compatibility, API and flag definitions, etc.

 - Expected to be responsive to review requests as per
-  [community expectations](REVIEWING.md)
+  [community expectations](REVIEWING.md).

- Mentor members and contributors
+- Mentor members and contributors.

- May approve code contributions for acceptance
+- Might approve code contributions for acceptance.

 ## Lead

@ -240,23 +235,23 @@ and approve design decisions for their area of ownership.

 Getting to be a lead of an existing working group:

- Recognized as having expertise in the group’s subject matter
+- Recognized as having expertise in the group’s subject matter.

- Approver for some part of the codebase for at least 3 months
+- Approver for some part of the codebase for at least 3 months.

- Member for at least 1 year or 50% of project lifetime, whichever is shorter
+- Member for at least 1 year or 50% of project lifetime, whichever is shorter.

- Primary reviewer for 20 substantial PRs
+- Primary reviewer for 20 substantial PRs.

- Reviewed or merged at least 50 PRs
+- Reviewed or merged at least 50 PRs.

- Sponsored by the technical oversight committee
+- Sponsored by the technical oversight committee.

 Additional requirements for leads of a new working group:

- Originally authored or contributed major functionality to the group's area
+- Originally authored or contributed major functionality to the group's area.

- An approver in the OWNERS file for the group’s code
+- An approver in the OWNERS file for the group’s code.

 ### Responsibilities and privileges

@ -270,23 +265,23 @@ The following apply to the area / component for which one would be an owner.

 - Perform issue triage on GitHub.

- Apply/remove/create/delete GitHub labels and milestones
+- Apply/remove/create/delete GitHub labels and milestones.

 - Write access to repo (assign issues/PRs, add/remove labels and milestones,
-  edit issues and PRs, edit wiki, create/delete labels and milestones)
+  edit issues and PRs, edit wiki, create/delete labels and milestones).

- Capable of directly applying lgtm + approve labels for any PR
+- Capable of directly applying lgtm + approve labels for any PR.

  - Expected to respect OWNERS files approvals and use
    [standard procedure for merging code](REVIEWING.md#merging-prs).

 - Expected to work to holistically maintain the health of the project through:

-  - Reviewing PRs
+  - Reviewing PRs.

-  - Fixing bugs
+  - Fixing bugs.

-  - Mentoring and guiding approvers, members, and contributors
+  - Mentoring and guiding approvers, members, and contributors.

 ## Administrator

@ -299,15 +294,15 @@ Administrators are responsible for the bureaucratic aspects of the project.
 ### Responsibilities and privileges

 - Manage the Knative GitHub repo, including granting membership and controlling
-  repo read/write permissions
+  repo read/write permissions.

- Manage the Knative Slack team
+- Manage the Knative Slack team.

- Manage the Knative Google group forum
+- Manage the Knative Google group forum.

- Manage any additional Knative technical collaboration assets
+- Manage any additional Knative technical collaboration assets.

- Expected to be responsive to membership and permission change requests
+- Expected to be responsive to membership and permission change requests.
  <!-- TODO SLA for admin response -->

 <!-- * TODO Manage the Google Search Console settings for knative.dev -->