WEP0, a proposal for the WEP process #1

ericholscher · 2019-10-10T14:20:13Z

This is the first Write the Docs Enhancement Proposal (WEP), which introduces the WEP process itself and proposes to implement it in the Write the Docs community.

The WEP process enables anyone from the community to propose process and policy changes to the community. The community then reviews the proposed change and if the change is accepted, the policy or process change is implemented in the community.

This "meta-WEP" follows the WEP process to show how the process works and to help the community learn how to use it.

Please read below and give us feedback to the process we're proposing!

Proposed WEP Timeline

November 4 - WEP Announced
December 4 - Decision on WEP, after 30 day discussion period

This is the first Write the Docs Enhancement Proposal (WEP), which introduces the WEP process itself and proposes to implement it in the Write the Docs community. The WEP process enables anyone from the community to propose process and policy changes to the community. The community then reviews the proposed change and if the change is accepted, the policy or process change is implemented in the community. This "meta-WEP" follows the WEP process to show how the process works and to help the community learn how to use it. Please read below and comment.

plaindocs

Looks good to me.

Tinkerer- · 2019-11-04T10:27:41Z

meta-issue: there's no slack channel yet to discuss it.
I'm missing a section 'consequences' in the WEP template. I'm used to work with Architecture Decision Records (see http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), and one of the good things I get from those is the description of positive and negative consequences of decisions.

ddbeck

I'm really excited that this is happening. Thank you for starting this!

Overall, I'm happy with the direction of this proposal. I've left a few comments and suggestions, mostly aimed at clearing up some points where I thought things were unclear or unspecific. Thank you again!

ddbeck · 2019-11-04T10:57:46Z

WEP0000_wep-proposal.rst

+- Content format must follow the WEP style as described in the **WEP format and style** section. This includes language, grammar, structure, and markup. The PR might be blocked until proper formatting rules are applied.
+- The WEP content is complete. If you want to submit a Work in Progress (WIP) draft before it is ready for pre-review, you can mark the PR as ``WIP`` and the review team will wait until the draft is ready.
+- **Allow edits from maintainers** option is selected. This helps the reviewer merge your WEP draft if it is accepted.
+- The PR is tagged with a **draft** flag, to indicate that it is in a draft state and is ready for pre-review. 


What is "tagged" here? Is this opening the PR in GitHub's draft status, a label on the PR, text in the WEP, or something else?

My understanding is this: https://github.com/writethedocs/weps/pull/1/files#diff-f47194e85dd085426bc962ab2fd3baf6R202

A GH action to parse that and set labels would be super cute.

I think that it boils down to labels that are manually assigned, rather than a draft state. Let's reword this to align with GH terminology.

ddbeck · 2019-11-04T11:14:34Z

WEP0000_wep-proposal.rst

+  Action: The WEP team merges the PR and stores the WEP in the ``accepted`` directory.
+
+Rejected
+  Reason: Community feedback led to disagreements about the WEP that cannot be resolved, or the original goal of the WEP is no longer considered an improvement to the community. 


no longer considered an improvement to the community

I think the passive voice here makes it hard to understand the process. Is this meant to be a characterization of the review discussion (e.g., community feedback leads to a negative consensus that the WEP should be rejected)? Or is this an independent conclusion of the WEP team (e.g., the WEP team reviews the final text and makes its own decision on whether its an improvement to the community)?

The former, I'd say.

Agreed that I think we meant the former. I guess we should have a state that is "rejected by the powers that be" -- perhaps Vetoed, which makes this more explicit?

I'm not comfortable with a Veto option here, since it seems a bit contradictory to the consensus idea. I made a suggestion to reword the text to make it more explicit, maybe it'll solve the question.

WEP0000_wep-proposal.rst

wep-template.rst

WEP0000_wep-proposal.rst

DavidBiesack · 2019-11-06T21:45:27Z

Consider looking at the pattern used at https://aip.dev/ if you have not already - similar to what you are trying to do here, and there may be some aspects of AIP you can reuse.

WEP0000_wep-proposal.rst

Co-Authored-By: Daniel D. Beck <[email protected]>

mjang · 2019-12-02T19:57:39Z

WEP0000_wep-proposal.rst

+The WEP process and system are administered by the following teams:
+
+Core Operations team
+  There are several reference in this WEP to the **core operations (CoreOps) team**. This team is currently known as the **core team** and the team description can be found on the `Core team page <https://www.writethedocs.org/team/#core-team>`_. The updated name is intended to reflect the purpose of the team more accurately in the context of its duties for the community. 


s/reference/references/

WEP0000_wep-proposal.rst

mjang · 2019-12-02T20:02:00Z

WEP0000_wep-proposal.rst

+
+Note that the process to join and leave teams is out of scope of this WEP and will be handled in a future WEP.
+
+At a very high level, the WEP submission process includes the following stages:


Should this be written in a more active voice, e.g. If you have an idea for , take the following steps:

I think this is more the definition of the process, I think we'll grow a "how to" guide in the future as we get more process around it.

mjang · 2019-12-02T20:04:19Z

WEP0000_wep-proposal.rst

+Pre-proposal
+............
+
+The WEP process begins with a new idea for Write the Docs. It is highly recommended that a single WEP contain a single key proposal or new idea. 


Does it have to be a "new idea"?

If the WEP contains multiple proposals, I think that would come out in the discussion.

I don't think we're going to judge things by any new-ness quality, it's more just a turn of phrase. Perhaps "process update" is more explicit?

In the tech writing world, the word "new" is usually redundant. I vote we clean it up and just say "idea".

WEP0000_wep-proposal.rst

mjang · 2019-12-02T20:09:57Z

WEP0000_wep-proposal.rst

+
+To help prepare the WEP draft, we encourage community members to discuss the idea publicly, for example in the Slack group, and gather initial community feedback before writing a full WEP. Public discussions on pre-proposals also help to make sure the idea is applicable to the entire community and not just to the author.
+
+A WEP can be co-authored by more than one community member, but we recommend keeping the number of co-authors small and choosing a representative who will submit the PR to the WEPs repository on behalf of the co-authors.


we recommend keeping the number of co-authors small

I'm not sure we should even mention this. But if you think it's important, I'd like an explanation.

If I were a WEP author, I'd want to have as many "co-sponsors" as possible.

There is a difference between "co-authors" and "co-sponsors". Co-authors are actively creating the WEP before it's submitted to community discussion, while co-sponsors should be enlisted during the discussion phase. The goal here is to distinguish ownership of the WEP creation and feedback implementation, and you probably don't want 10 people authoring the same WEP for logistical reasons :)

I think we stole this from the PEP process, but I think the goal is to have a couple people responsible for shepherding it. If 5 people come together it becomes hard to figure out who is in charge and can make decisions. I think smaller is definitely better in terms of the proposal team, but not in terms of who looks at and reviews it.

Appreciate the explanation. Then maybe s/on behalf of the co-authors/on behalf of all supporters of the WEP/

(The current text, to me, implies that support is limited to the authors)

I wrote in a suggestion to expand this paragraph and differentiate between authors and supporters. Feel free to edit/adapt as needed.

WEP0000_wep-proposal.rst

mjang · 2019-12-02T20:11:35Z

WEP0000_wep-proposal.rst

+
+The WEP draft must follow these guidelines:
+
+- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear.


I'd leave out "WEP is actionable and implementable"

Agreed, it's a bit of a weird sentence, the second one is more clear 👍

mjang · 2019-12-02T20:12:46Z

WEP0000_wep-proposal.rst

+The WEP draft must follow these guidelines:
+
+- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear.
+- WEP fits the scope of the WEP process, as described in **Scope of WEPs**. WEPs that are out of scope of the process will be rejected by the reviewer.


s/reviewer/WEP team/

(since anyone can review a PR, we should be specific)

WEP0000_wep-proposal.rst

mjang · 2019-12-02T20:15:29Z

WEP0000_wep-proposal.rst

+
+After the pull request for the WEP draft is submitted, a WEP team member reviews the pull request to make sure it adheres to the guidelines. If the WEP is clearly not ready, the reviewer might reject the pull request and ask the author to submit a new WEP after the problems have been fixed.
+
+The reviewer does not vote on the proposed change itself, and only reviews the WEP for scope compliance, format, and completeness. The pre-review period is usually one week, but might change based on the scope of the pre-review feedback and the availability of the author to implement changes.


That suggests the "reviewer" is different from the "WEP team", which upon first reading contradicts earlier text

The term "reviewer" is defined in the first paragraph as "a WEP team member... reviews"

I've added WEP team reviewer to be more explicit, which seems fine.

WEP0000_wep-proposal.rst

mjang · 2019-12-02T20:17:46Z

WEP0000_wep-proposal.rst

+Community review, discussion, and updates
+.........................................
+
+The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. 


The "community review" is different from the "reviewer" who looks at scope and compliance? The redundancy in these terms is confusing me

Yea, the WEP team does the initial review for acceptance, then the wider community will look at it and have input. There are effectively 2 stages of review.

I've changed the language to decided on, since reviewed here I agree is ambiguous.

Co-Authored-By: Mike Jang <[email protected]>

ericholscher

Thanks for the feedback Mike -- I've pushed up a few clarifications.

ericholscher · 2019-12-04T13:07:36Z

WEP0000_wep-proposal.rst

+
+Note that the process to join and leave teams is out of scope of this WEP and will be handled in a future WEP.
+
+At a very high level, the WEP submission process includes the following stages:


I think this is more the definition of the process, I think we'll grow a "how to" guide in the future as we get more process around it.

ericholscher · 2019-12-04T13:08:21Z

WEP0000_wep-proposal.rst

+Pre-proposal
+............
+
+The WEP process begins with a new idea for Write the Docs. It is highly recommended that a single WEP contain a single key proposal or new idea. 


I don't think we're going to judge things by any new-ness quality, it's more just a turn of phrase. Perhaps "process update" is more explicit?

ericholscher · 2019-12-04T13:10:31Z

WEP0000_wep-proposal.rst

+
+The WEP draft must follow these guidelines:
+
+- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear.


Agreed, it's a bit of a weird sentence, the second one is more clear 👍

WEP0000_wep-proposal.rst

ericholscher · 2019-12-04T13:14:16Z

WEP0000_wep-proposal.rst

+
+After the pull request for the WEP draft is submitted, a WEP team member reviews the pull request to make sure it adheres to the guidelines. If the WEP is clearly not ready, the reviewer might reject the pull request and ask the author to submit a new WEP after the problems have been fixed.
+
+The reviewer does not vote on the proposed change itself, and only reviews the WEP for scope compliance, format, and completeness. The pre-review period is usually one week, but might change based on the scope of the pre-review feedback and the availability of the author to implement changes.


I've added WEP team reviewer to be more explicit, which seems fine.

ericholscher · 2019-12-04T13:15:15Z

WEP0000_wep-proposal.rst

+Community review, discussion, and updates
+.........................................
+
+The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. 


Yea, the WEP team does the initial review for acceptance, then the wider community will look at it and have input. There are effectively 2 stages of review.

ericholscher · 2019-12-04T13:15:39Z

WEP0000_wep-proposal.rst

+Community review, discussion, and updates
+.........................................
+
+The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. 


I've changed the language to decided on, since reviewed here I agree is ambiguous.

thatdocslady

Some suggestions, some discussions resolved, and other beasts :)

thatdocslady · 2019-12-04T13:52:20Z

WEP0000_wep-proposal.rst

+- Content format must follow the WEP style as described in the **WEP format and style** section. This includes language, grammar, structure, and markup. The PR might be blocked until proper formatting rules are applied.
+- The WEP content is complete. If you want to submit a Work in Progress (WIP) draft before it is ready for pre-review, you can mark the PR as ``WIP`` and the review team will wait until the draft is ready.
+- **Allow edits from maintainers** option is selected. This helps the reviewer merge your WEP draft if it is accepted.
+- The PR is tagged with a **draft** flag, to indicate that it is in a draft state and is ready for pre-review. 


I think that it boils down to labels that are manually assigned, rather than a draft state. Let's reword this to align with GH terminology.

WEP0000_wep-proposal.rst

thatdocslady · 2019-12-04T13:56:18Z

WEP0000_wep-proposal.rst

+  Action: The WEP team merges the PR and stores the WEP in the ``accepted`` directory.
+
+Rejected
+  Reason: Community feedback led to disagreements about the WEP that cannot be resolved, or the original goal of the WEP is no longer considered an improvement to the community. 


I'm not comfortable with a Veto option here, since it seems a bit contradictory to the consensus idea. I made a suggestion to reword the text to make it more explicit, maybe it'll solve the question.

WEP0000_wep-proposal.rst

Co-Authored-By: Mikey Ariel <[email protected]>

WEP0000_wep-proposal.rst

Co-Authored-By: Mikey Ariel <[email protected]>

WEP0000_wep-proposal.rst

Co-Authored-By: Mikey Ariel <[email protected]>

ericholscher · 2019-12-13T19:27:51Z

Feels like this is ready to be merged. I know we'll have to continue to evolve our approaches as we implement this new system, but I'm confident it will be better than what we're doing now :)

Excited for a whole new world 🎉

ericholscher added the draft WEP is currently in a draft state label Oct 10, 2019

plaindocs approved these changes Oct 15, 2019

View reviewed changes

mxsasha added ready-for-discussion WEP is ready to be discussed by the community. and removed draft WEP is currently in a draft state labels Oct 30, 2019

JustinW80 approved these changes Nov 3, 2019

View reviewed changes

ddbeck suggested changes Nov 4, 2019

View reviewed changes

jamesrhea reviewed Nov 4, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

scottydocs reviewed Nov 6, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

scottydocs reviewed Nov 6, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

plaindocs reviewed Nov 12, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

mxsasha and others added 6 commits November 13, 2019 13:41

Remove obsolete action item.

26588a5

Co-Authored-By: Daniel D. Beck <[email protected]>

Fix email address typo.

d0b7ff5

Clarify review period length earlier on.

b44fc59

Fix grammar error.

1cea2d6

Update wep-template.rst

decfc9d

Co-Authored-By: Daniel D. Beck <[email protected]>

Update wep-template.rst

574c541

Co-Authored-By: Daniel D. Beck <[email protected]>

mjang reviewed Dec 2, 2019

View reviewed changes

WEP0000_wep-proposal.rst Show resolved Hide resolved

mjang reviewed Dec 2, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

mjang reviewed Dec 2, 2019

View reviewed changes

WEP0000_wep-proposal.rst Show resolved Hide resolved

mjang reviewed Dec 2, 2019

View reviewed changes

WEP0000_wep-proposal.rst Show resolved Hide resolved

mjang reviewed Dec 2, 2019

View reviewed changes

WEP0000_wep-proposal.rst Show resolved Hide resolved

mjang reviewed Dec 2, 2019

View reviewed changes

Update WEP0000_wep-proposal.rst

d7b581c

Co-Authored-By: Mike Jang <[email protected]>

ericholscher commented Dec 4, 2019

View reviewed changes

Address feedback from Mike: attempt to clarify process more

14e3606

thatdocslady reviewed Dec 4, 2019

View reviewed changes

ericholscher and others added 3 commits December 4, 2019 16:53

Update WEP0000_wep-proposal.rst

092f1d4

Co-Authored-By: Mikey Ariel <[email protected]>

Update WEP0000_wep-proposal.rst

7770266

Co-Authored-By: Mikey Ariel <[email protected]>

Update WEP0000_wep-proposal.rst

5d71e61

Co-Authored-By: Mikey Ariel <[email protected]>

thatdocslady mentioned this pull request Dec 11, 2019

Create a how-to-WEP guide #2

Open

thatdocslady reviewed Dec 11, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

Update WEP0000_wep-proposal.rst

5c015ef

Co-Authored-By: Mikey Ariel <[email protected]>

ericholscher commented Dec 12, 2019

View reviewed changes

WEP0000_wep-proposal.rst Show resolved Hide resolved

thatdocslady reviewed Dec 12, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

thatdocslady reviewed Dec 12, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

thatdocslady reviewed Dec 12, 2019

View reviewed changes

WEP0000_wep-proposal.rst Outdated Show resolved Hide resolved

ericholscher and others added 2 commits December 12, 2019 16:45

Update WEP0000_wep-proposal.rst

dd548b8

Co-Authored-By: Mikey Ariel <[email protected]>

Apply suggestions from code review

0287aff

Co-Authored-By: Mikey Ariel <[email protected]>

mxsasha approved these changes Dec 13, 2019

View reviewed changes

thatdocslady approved these changes Dec 13, 2019

View reviewed changes

ericholscher merged commit 0287aff into master Dec 13, 2019

mxsasha deleted the wep0-proposal branch April 11, 2022 11:43


		Note that the process to join and leave teams is out of scope of this WEP and will be handled in a future WEP.

		At a very high level, the WEP submission process includes the following stages:


		To help prepare the WEP draft, we encourage community members to discuss the idea publicly, for example in the Slack group, and gather initial community feedback before writing a full WEP. Public discussions on pre-proposals also help to make sure the idea is applicable to the entire community and not just to the author.

		A WEP can be co-authored by more than one community member, but we recommend keeping the number of co-authors small and choosing a representative who will submit the PR to the WEPs repository on behalf of the co-authors.


		The WEP draft must follow these guidelines:

		- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear.


		After the pull request for the WEP draft is submitted, a WEP team member reviews the pull request to make sure it adheres to the guidelines. If the WEP is clearly not ready, the reviewer might reject the pull request and ask the author to submit a new WEP after the problems have been fixed.

		The reviewer does not vote on the proposed change itself, and only reviews the WEP for scope compliance, format, and completeness. The pre-review period is usually one week, but might change based on the scope of the pre-review feedback and the availability of the author to implement changes.

WEP0, a proposal for the WEP process #1

WEP0, a proposal for the WEP process #1

Conversation

ericholscher commented Oct 10, 2019 • edited Loading

Proposed WEP Timeline

plaindocs left a comment

Choose a reason for hiding this comment

Tinkerer- commented Nov 4, 2019

ddbeck left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DavidBiesack commented Nov 6, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thatdocslady left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher commented Dec 13, 2019

ericholscher commented Oct 10, 2019 •

edited

Loading