openedx / open-edx-proposals

Proposals for Open edX architecture, best practices and processes
http://open-edx-proposals.readthedocs.io/
Other
43 stars 32 forks source link

Reword OEP-1 to be from a 3rd-person, role-agnostic point of view #429

Closed kdmccormick closed 11 hours ago

kdmccormick commented 2 years ago
kdmccormick commented 1 year ago

Unassigning myself as I have no current plans to do this.

sarina commented 2 months ago

I don't know if I agree on this. Why should this be written in a 3rd party voice? What problem exists because the word "you" is used?

The way that "you" is used is approachable to me and I can follow it. eg this line:

If you’re not sure who would make a good Arbiter, you should reach out to the Architecture Group; please feel free to participate in the discussion and help choose an arbiter you feel you can work with.

Would it really be better for it to say

The Architecture Group should be leveraged when the authors of a new OEP are not sure who would make a good arbiter. When starting a conversation, authors should participate in the discussion so that the chosen arbiter is one they feel they can work with

? I don't see what the removal of "you" added except a couple backflips in my mind to finagle this sentence into 3rd party voice.

Perhaps your concern is that this is written solely from the POV of what an OEP Author does in a way that might alienate an Arbiter? The section is called "Submitting an OEP" so I would expect the section to be written in a way that's talking to the author(s).

sarina commented 2 months ago

Separate "role responsibility" section should exist for each role, linking out to relevant parts of the process

What roles exist beyond Author(s) and Arbiter?

kdmccormick commented 11 hours ago

I don't exactly remember what I was concerned about out with this issue. I agree with you that rewording those sections from 2nd to 3rd person would just make them harder to read.