Reality and Best Practices of Formal Reviews added (#361)

formal-reviews/modules/ROOT/pages/index.adoc

@@ -9,7 +9,7 @@ Official repository: https://github.com/boostorg/website-v2-docs
 = Introduction to Boost Formal Reviews
 :navtitle: Introduction
 
-This Formal Review Guide provides information for the three main roles in library submission:
+This Formal Review Guide provides information for the main roles in library submission:
 
 . The authors who wish to submit the library to the Boost collection: refer to the xref:submissions.adoc[].
 . The _Review Manager_ who's job it is to lead and coordinate the review process: refer to xref:managing-reviews.adoc[].

formal-reviews/modules/ROOT/pages/managing-reviews.adoc

@@ -33,17 +33,32 @@ The review manager works through the following process:
 
 . Urges people to do reviews if they aren't forthcoming.
 
-. Follows review discussions regarding the library, moderating or answering questions as needed.
+. Follows review discussions regarding the library, moderating or answering questions as needed. It is the review manager's job to give reviewers the benefit of the doubt and to try to coax a serious review out of participants, by asking pertinent questions.
 
 . Asks the <<Review Wizards>> for permission to extend the review schedule if it appears that too few reviews will be submitted during the review period.
 
 . Decides if there is consensus to accept the library and if there are any conditions attached. Consensus is not the same as a vote. *The review manager has discretion to weigh opinions based on authority or thoughtfulness.*
++
+[[realitycheck]]
+Reality Check:: The review manager is _not_ supposed to impartially reflect the community opinion, as expressed in the form of formal reviews. Instead, the review manager's role is to decide whether the library should be accepted, and the reviews help them with this, rather than decide for them. Simply put, the review manager does not impartially tally votes - reviews are not votes.
++
+A review manager _can_ write a review themselves, though this process is independent of their role of review manager. 
++
+The review process is more like a court - with the judge (the review manager) asking _"Does the library meet the required standards for acceptance as a Boost library?"_.  This question is resolved by various advocates presenting their cases, criticizing other advocates cases, presenting facts, logical arguments, their own experiences, and so on.  The judge's job is to weigh all this and reach a decision. And they may add conditions on acceptance, or not. If concensus between judge and authors cannot be reached on meeting any conditions - the process ends without a resolution (the mistrial). 
++
+The review manager is - for better or worse - personally responsible for making the decision, defending the results, and dealing with future criticism.  Their name will be public.  This is not a job for everyone.
++
+Sometimes the judging process is going to produce irreconcilable differences, and continued discussions about the "verdict" are a fact of life. With any process there will be "winners" and "losers". So it's not about everyone being happy at the end of the day.
++
+If, years from now, someone would like to know why a library was accepted or rejected, they _only_ needs to read the court documents (the review posts and the review summary), and should come away with the correct understanding of what happened and why.
 
 . Posts a notice of the review results on the https://lists.boost.org/mailman/listinfo.cgi/boost-users[Boost users mailing list] as well as the https://lists.boost.org/mailman/listinfo.cgi/boost[Boost developers' mailing list] and https://lists.boost.org/mailman/listinfo.cgi/boost-announce[Boost-announce mailing list]. A rationale is also helpful, but its extent is up to the review manager. If there are suggestions, or conditions that must be met before final inclusion, they should be stated. Concerns about the timeliness or quality of the review report should be brought to the <<Review Wizards>> off-list.
++
+Ideally, the review summary should contain all the information the manager has taken into account when coming to a decision. If there were discussions out of band, they need to be summarized. If there were discussions _on the list_ that haven't made their way into the formal reviews, they should be summarized too. Refer to the xref:writing-reviews.adoc#bestpractices[Best Practices] section on Writing Reviews for some issues to look out for. 
 
 == Becoming a Review Manager
 
-To manage a review, you should have experience with the review process and knowledge of the library's domain. To volunteer to become a review manager, contact the current <<Review Wizards>>.
+To manage a review, you should have experience with the review process and ideally expert knowledge of the library's domain. To volunteer to become a review manager, contact the current <<Review Wizards>>.
 
 [[reviewwizards]]
 === Review Wizards

formal-reviews/modules/ROOT/pages/writing-reviews.adoc

@@ -13,7 +13,7 @@ The goal of a Boost library review is to improve a candidate library through con
 
 Your comments may be brief or lengthy. The review manager needs your evaluation of the library. If you identify problems in your evaluation, try to categorize them as _minor_, _serious_, or _showstoppers_.
 
-Include questions for the library authors. Authors are interested in defending their library. If you don't get a response to your question quickly, be patient; if it takes too long or you don't get an answer you feel is sufficient, ask again or try to rephrase the question. Clarity is important, English is not the native language of many Boost developers.
+Ask questions for the library authors, on the https://lists.boost.org/mailman/listinfo.cgi/boost[Boost Developers Mailing List], so all interested parties can see it. Authors are interested in defending their library. If you don't get a response to your question quickly, be patient; if it takes too long or you don't get an answer you feel is sufficient, ask again or try to rephrase the question. Clarity is important, English is not the native language of many Boost developers. Try to get your questions answered before you submit your review.
 
 Here's a structured approach to writing a review of a library, covering all the bases:
 
@@ -98,6 +98,21 @@ If it's helpful, cut and paste the following template into your email text when
 * What is your verdict: Yes, No, or Yes with changes?
 ```
 
+[[bestpractices]]
+== Best Practices
+
+From experience, there a number of more common pitfalls when writing reviews and engaging in review feedback discussions, so keep the following in mind:
+
+* Literally, keep on the same page. Submissions, discussions, comment should always be on the https://lists.boost.org/mailman/listinfo.cgi/boost[Boost Developers Mailing List] and not on Slack, Reddit, in personal email, or any other media. 
+
+* Elaborate in full. If you have series technical feedback on a library then explain yourself in detail. Try to avoid "teaser" type comments where other developers might feel you are onto something, but they are just not sure what.
+
+* Reviews needs to be self-contained. It's not a starting point for a discussion. Nobody is obligated to ask you clarifying questions, and there should be no missing parts that you fill in later in subsequent posts. This means that if you have questions about the library that you feel need to be answered by the author or review manager, you should ask these questions _before_ you submit your review.
+
+* Do not expect complete agreement. Too much compromise, consensus, in engineering endeavors leads to poorer design.
+
+* Refer to the xref:managing-reviews.adoc#realitycheck[Reality Check] section in the topic on Review Managers for clarity on the role of your review.
+
 == See Also
 
 * xref:contributor-guide:ROOT:getting-involved.adoc[]