Imrovements to api-review-process.md#38378
Imrovements to api-review-process.md#38378danmoseley merged 3 commits intodotnet:masterfrom SingleAccretion:Improvements_To_API_Review_doc
Conversation
|
Thanks @SingleAccretion I pushed some other changes - do they look OK? Better to use a more modern example so I updated that. Ideally this would all be written with active voice ("you" instead of "the requester") to be easier to read. |
|
@danmosemsft Yes, I very much agree with the changes. The issue you mentioned kind of goes deeper in my opinion (I actually had a little write up about this at first in the PR description, but later cut it out for brevity). The document addresses two kinds of people at once, and because of that cannot really use "you" effectively, since in the first half, "you" would mean "the requester", but in the second half, it would be "the maintainer", someone who is looking for guidance on how the review process works from their perspective. I personally think this is fine, since having two documents/two sections that describe basically the same process would (in my opinion) be worse than the tradeoff of using a lot of passive voice. Edit: that said, the document already uses active voice in the second half, so perhaps this is not actually a problem (as in, we could use it everywhere and it would be OK)? |
|
@SingleAccretion sounds fine, I've merged as is (thank you) and if you feel like any future improvements just throw up a new PR. |
This is the result of @danmosemsft's comment here.
This PR adds three links to the "API Review Process" document:
I also initially thought of adding a link to apisof.net, but after exploring this possibility decided against it due to the lack of a good place for it.