[PATCH v4 0/2] MyFirstContribution: discuss then reroll

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

The MyFirstContribution document tells readers how to send v1, how
to send v2, and then how to respond to reviews, in that order.  It
uses a fairly weak language "it is a good manners to ..." to respond
to reviews before rerolling.

On the mailing list, we find ourselves more and more frequently
having to tell new contributors not to send updated iterations of
their patches before having any review discussion on the current
iteration.

Here is an attempt to rectify the situation.

The first patch reorders the sections to explain how to send v1, how
to respond to reviews, before explaining how to send v2.

The second patch rewrites the "how to respond to reviews" section to
strengthen the "it is a good manners" by replacing it with "do not
send v2 before you have finished discussing v1".

Relative to v3, this rewrites the "responding to reviews" section
more tightly, shaving about 1/5 words, without losing substance.

Hopefully this will be the final iteration of this series.

 1/2: MyFirstContribution: move "how to send v2" after discussing reviews
 2/2: MyFirstContribution: clarify that "reviewing" is a discussion

 Documentation/MyFirstContribution.adoc | 273 +++++++++++--------------
 1 file changed, 125 insertions(+), 148 deletions(-)

Range-diff against v3:
1:  e6f4a2a7ca = 1:  9db8ec4b98 MyFirstContribution: move "how to send v2" after discussing reviews
2:  27f47d7d65 ! 2:  88abda272c MyFirstContribution: clarify that "reviewing" is a discussion
    @@ Commit message
         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 to design
    -    what the next iteration should look like.
    +    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
    @@ Documentation/MyFirstContribution.adoc: previous one" patches over 2 days), revi
     -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.
    ++After a few days, you may receive comments on your patch series.
    ++Carefully read them to understand the reviewers' perspective, and do
    ++not hesitate to ask for clarification.
     +
    -+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.
    ++Reviewers may also ask about your proposed commit log or the changes.
    ++Answer these in your response.  They often ask because the patch needs
    ++clarification; use this feedback to improve your writing, and update
    ++the patch so the next reader does not have to ask the same question.
     +
    -+Do not start coding, let alone send the next version of your patch,
    -+until you have finished discussing the current one so both sides know
    -+what to expect.  This saves time for everyone.  Reviewers can respond
    -+to your explanation before you spend time preparing a patch they might
    -+reject, and they will not have to inspect 'v2' only to find their
    ++Do not start coding, much less send the next version, until you finish
    ++discussing the current one and both sides know what to expect.  This
    ++saves time, lets reviewers respond before you write a patch they have
    ++to reject, and avoids forcing them to inspect 'v2' only to find their
     +concerns unaddressed.
     +
    -+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.
    ++Do not iterate too quickly; at most one iteration per day is good
    ++practice.  This allows multiple reviewers to comment, gives
    ++participants in different time zones a fair chance, lets you batch
    ++feedback, and gives you time to digest comments before coding.
     +
    -+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.
    ++Knowing you cannot immediately send another version encourages careful
    ++self-review, letting you catch small mistakes yourself so reviewers
    ++can focus on design 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-336-g6ca398b529