[PATCH v2 2/2] MyFirstContribution: clarify that "reviewing" is a discussion

[Junio C Hamano <gitster@pobox.com>]

The latter half of the "We sent our initial patch.  Now what?"
section largely duplicates the discussion on what to do after
getting a review, which is covered in the subsequent section.  Also,
the "Reviewing" section does not make it clear from the beginning
that reviewing is a process of discussion with your reviewers.

Rewrite the "Reviewing" section with stronger language to discourage
sending a 'v2' iteration before working together with the reviewers
to prepare for it.  In particular, replace the weak "it is a good
manners to do so" with a firmer "do not send v2 before you are
done."

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 78 +++++++++++---------------
 1 file changed, 32 insertions(+), 46 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 682c797e3c..3fd6587e5a 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1314,56 +1314,42 @@ previous one" patches over 2 days), reviewers would strongly prefer if a
 single polished version came 2 days later instead, and that version with
 fewer mistakes were the only one they would need to review.
 
-This consideration applies not only when going from the initial patch to v2,
-but also to later iterations of the same series. There is no fixed rule for how
-long to wait before sending a new version. A useful default is to send at most
-one new version of the same patch series per day. This gives multiple reviewers
-time to comment, gives reviewers across time zones a fair chance to
-participate, lets you batch feedback together, and gives you time to think
-through the comments you received. Knowing that you should not immediately send
-another version also encourages you to review the patches more carefully before
-sending them, catch small mistakes such as typos and off-by-one errors
-yourself, and let reviewers spend more of their attention on design,
-algorithms, and other substantial issues.
-
-The right timing depends on the topic and the feedback. Larger series usually
-need more review time. If the only comments so far are minor, such as typo
-fixes, it often makes sense to wait a little longer in case deeper reviews are
-still coming. If the comments call for substantial rework, do not rush out an
-updated version before you have reviewed the larger changes carefully. Instead,
-reply to the review that prompted the rewrite, say that you are preparing a
-substantial rework, and mention which parts of the current series will become
-obsolete so reviewers can avoid spending time on them until the updated series
-is ready.
-
 
 [[reviewing]]
 === Responding to Reviews
 
-After a few days, you will hopefully receive a reply to your patchset with some
-comments. Woohoo! Now you can get back to work.
-
-It's good manners to reply to each comment in the mailing list discussion
-instead of letting the next version of your patch be your only response. Tell
-the reviewer whether you plan to make the suggested change, keep the original,
-or pursue a different approach. This way reviewers can respond to your reasoning
-before you spend time preparing a version they may not agree with, and later do
-not need to inspect your v2 to figure out whether you implemented their comment
-or not.
-
-Reviewers may ask you about what you wrote in the patchset, either in
-the proposed commit log message or in the changes themselves.  You
-should answer these questions in your response messages, but often the
-reason why reviewers asked these questions to understand what you meant
-to write is because your patchset needed clarification to be understood.
-
-Do not be satisfied by just answering their questions in your response
-and hear them say that they now understand what you wanted to say.
-Update your patches to clarify the points reviewers had trouble with,
-and prepare your v2; the words you used to explain your v1 to answer
-reviewers' questions may be useful thing to use.  Your goal is to make
-your v2 clear enough so that it becomes unnecessary for you to give the
-same explanation to the next person who reads it.
+After a few days, you will hopefully receive a reply to your patch
+series with some comments.  Carefully read them to understand the
+reviewers' perspective.  Do not hesitate to ask for clarification if
+you do not understand their suggestions.
+
+Reviewers may also ask about what you wrote in the patch series,
+either in the proposed commit log message or in the changes
+themselves.  Answer these questions in your response.  Often,
+reviewers ask because your patch series needs clarification to be
+understood; use this as feedback to improve the clarity of your
+writing.  When answering, remember to update the patch itself so that
+the next reader will not need to ask the same question.
+
+Do not start coding, much less send the next version of your patch,
+until you have finished discussing the current round of reviews with
+your reviewers.  This saves time for both you and your reviewers.
+They can respond to your reasoning before you spend time preparing a
+version they might reject, and they will not have to inspect your 'v2'
+to check if you addressed their concerns.
+
+Do not iterate too quickly.  Limiting yourself to at most one
+iteration of the same patch series per day is good practice; it takes
+time to fully discuss the current version before working on the next.
+This allows multiple reviewers to comment, gives participants in
+different time zones a fair chance to participate, lets you batch
+feedback, and gives you time to digest comments before coding again.
+
+Knowing that you cannot immediately send another version encourages
+you to review your patches more carefully before sending.  You can
+catch small mistakes like typos and off-by-one errors yourself,
+allowing reviewers to focus on design, algorithms, and other
+substantive issues.
 
 If you are going to push back on a comment, be polite and explain why you feel
 your original is better; be prepared that the reviewer may still disagree with
-- 
2.56.0-321-g29a826976d