Skip to content

Imrovements to api-review-process.md#38378

Merged
danmoseley merged 3 commits intodotnet:masterfrom
SingleAccretion:Improvements_To_API_Review_doc
Jun 25, 2020
Merged

Imrovements to api-review-process.md#38378
danmoseley merged 3 commits intodotnet:masterfrom
SingleAccretion:Improvements_To_API_Review_doc

Conversation

@SingleAccretion
Copy link
Contributor

This is the result of @danmosemsft's comment here.

This PR adds three links to the "API Review Process" document:

  • A link to the template for an API proposal: as an addition to "a good issue" example.
  • A link to the YouTube playlist with API reviews: to mention that the process of review is actually public.
  • http://aka.ms/ready-for-api-review: as a useful link for people interested in API reviews.

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.

@SingleAccretion SingleAccretion changed the title Update api-review-process.md Imrovements to api-review-process.md Jun 25, 2020
@danmoseley
Copy link
Member

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.

@SingleAccretion
Copy link
Contributor Author

SingleAccretion commented Jun 25, 2020

@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)?

@danmoseley danmoseley merged commit 125dfe7 into dotnet:master Jun 25, 2020
@danmoseley
Copy link
Member

@SingleAccretion sounds fine, I've merged as is (thank you) and if you feel like any future improvements just throw up a new PR.

@ghost ghost locked as resolved and limited conversation to collaborators Dec 8, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants