Hi everybody. I'm quite nervous about writing this post, but there was an issue when discussing one of the latest proposals, where some reviewers couldn’t agree with the authors on how much background information should be explained in the proposal and how educational in general the proposal should be. I’m hesitant to link to the discussion, but I feel that the problem raised there did not come to a conclusive understanding of what reviewers can possibly expect from proposal authors and vice versa, and it seemed to me that some feelings were unnecessarily hurt because of this.
I personally understand both parties though, and I feel that the whole community would benefit if we could provide a way to enhance the communication. I’m not sure if the discussion should be repeated though, so I quickly summarise the points being argued by the parties:
- it is generally expected (or feels to me that way) that a reviewer has to be very comfortable with the topic being discussed, possibly having encountered its counterpart in other programming languages or libraries;
- reviewers, however, might lack mechanisms to self-audit their familiarity with the topic;
- proposal authors generally neither can preemptively address all possible questions in the proposal, nor dilute the discussion by answering them during the review as this can be counterproductive;
- depending on the proposal topic, however, it might turn out that the possession of compiler and/or language development skills is quite crucial for a successful discussion, while the broader community is generally comprised of members who are only familiar with the language as a user.
There might be many ways to address this, however, I feel that I have a relatively low-effort solution that might still be quite effective: introduce a "Prior knowledge" section to the proposal template.
This section would contain a short list of concepts, links to educational resources and possibly past proposals/discussions that the proposal authors deem to be effective in introducing a reviewer to the topic. This helps both parties and achieves several goals:
- relieves the need of directly writing explanations from proposal authors,
- ensures that the proposal authors are on the same page with reviewers,
- ensures that reviewers get acquainted with the topic directly from the best resources out there, as otherwise quite often people need to rely on serendipity rather than their sheer passion to learn,
- provides a way for reviewers to privately audit their knowledge instead of being struck by a comment on their ignorance,
- if this section is filled before the proposal is scheduled for review, reviewers might have enough time to properly introduce themselves to the topic to be more effective in reviewing and only ask additional questions if the provided material hasn’t answered them,
- allows for other suggestions to the list via a simple PR,
- provides educational value for the community even past review, while still staying on topic,
- reserves the “Alternatives considered” section for more topical handling of the said alternatives.
Please let me know what you think. This still requires some additional effort from proposal authors, but I’m unaware of other possibilities to welcomingly address the issue, especially that reviewers generally are extremely interested in increasing their knowledge level themselves.