Re: [PATCH v7] MyFirstContribution: add avenues for getting help

[Emily Shaffer <emilyshaffer@google.com>]

On Thu, Feb 06, 2020 at 11:49:29AM -0800, Emily Shaffer wrote:
> On Thu, Feb 06, 2020 at 08:33:54AM -0800, Junio C Hamano wrote:
> > SZEDER Gábor <szeder.dev@gmail.com> writes:
> > 
> > > On Fri, Jan 24, 2020 at 03:44:40PM -0800, Junio C Hamano wrote:
> > >
> > >> ...  The more important part, from my point of view,
> > >> is that we offer choices (the proposed doc update illustrates
> > >> three).
> > >
> > > I remember a discussion about whether that list and its archive should
> > > be open or closed, and I agree that offering choices is good.
> > > However, since that mentoring list requires registration, we have to
> > > carefully consider how to present it to newcomers.
> > >
> > > Openly accessible knowledge is a fundamental value, and it's the
> > > foundation of open source.  Therefore, we definitely should not direct
> > > newcomers to a closed mailing list as the first option, it can only be
> > > a fallback.
> > 
> > I am not that dogmatic ;-) I would be very unhappy and probably
> > would not have joined if the main development community was closed,
> > but I do not think the "knowledge" the "closed mentoring list for
> > those who are shy" are meant to impart to newbies will be something
> > that will be so well kept secret that are shared among only those in
> > the closed list.  I expect the mentoring list to be repeating what
> > those who graduated "new"-ness consider pretty much common public
> > knowledge.
> > 
> > Having said that, my reading did hiccup when queuing Emily's text,
> > in that it listed the mentoring list first, and (more problematic)
> > the only choice among the three described with a word "great" was
> > that one.  Also, now I re-read it, the last sentence "You must join
> > the group to view messages or post", without explaining why it is
> > set up that way is bound to give a wrong impression, I suppose.  I
> > presume that the reason why those who wanted to make the mentoring
> > list closed was because they thought it would be nicer for shysters,
> > but if that is the case, it probably is better to spell that out.
> 
> Sure. I think I didn't do so in an effort to be brief. I'll think on
> this today and send some suggestions here (rather than rerolling).
> 
> > 
> > > The text should list git@vger as the first option, since that's the
> > > only open mailing list we have, it should clearly emphasize that
> > > newcomers are very welcome, and should explicitly encourage them to
> > > post their questions here, no matter how trivial or silly they think
> > > those questions are, we'll be always glad to answer them.
> > 
> > I have no problem with seeing an expanded invitation to the main
> > list.  I do not have a strong opinion on the order of three items.
> 
> Me neither, and placing git@vger first does give me an opportunity to
> say something like "if you feel worried about asking publicly, this list
> is a more private setting" in reference to the mentors list. So that's
> an option I could get behind.

How about something like this?

I was trying to achieve the following goals:

 - Try to remove bias:
   - Don't make git@vger sound like a last-ditch effort or scary place.
   - Don't call git-mentoring@ "great", rather explain why it was
     created
   - Don't imply that all contributors who want to help are present on
     mentoring list, or that all contributors who aren't present on
     mentoring list don't want to help - just indicate that all
     contributors on mentoring list do want to help
 - Explain reasoning around git-mentoring@:
   - avoiding the public eye (and that's why viewing is restricted)
   - targeted membership (people joined because they want to help)

I'm no professional writer, so I expect there's more work to be done.
When we have something we're happy with then I'll send a formal patch.

 - Emily

-- >8 --

---
 Documentation/MyFirstContribution.txt | 29 +++++++++++++++------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 522c75099d..427274df4d 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -28,11 +28,24 @@ useful additional context:
 
 If you get stuck, you can seek help in the following places.
 
+==== git@vger.kernel.org
+
+This is the main Git project mailing list where code reviews, version
+announcements, design discussions, and more take place. Those interested in
+contributing are welcome to post questions here. The Git list requires
+plain-text-only emails and prefers inline and bottom-posting when replying to
+mail; you will be CC'd in all replies to you. Optionally, you can subscribe to
+the list by sending an email to majordomo@vger.kernel.org with "subscribe git"
+in the body. The https://lore.kernel.org/git[archive] of this mailing list is
+available to view in a browser.
+
 ==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
 
-This mailing list is targeted to new contributors and is a great place to post
-questions and receive kind, detailed answers from volunteers on the Git
-project. You must join the group to view messages or post.
+This mailing list is targeted to new contributors and was created as a place to
+post questions and receive answers outside of the public eye of the main list.
+Veteran contributors who are especially interested in helping mentor newcomers
+are present on the list. In order to avoid search indexers, group membership is
+required to view messages; anyone can join and no approval is required.
 
 ==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode
 
@@ -46,16 +59,6 @@ respond to you. It's better to ask your questions in the channel so that you
 can be answered if you disconnect and so that others can learn from the
 conversation.
 
-==== git@vger.kernel.org
-
-This is the main Git project mailing list where code reviews, version
-announcements, design discussions, and more take place. The Git list
-requires plain-text-only emails and prefers inline and bottom-posting when
-replying to mail; you will be CC'd in all replies to you. Optionally, you can
-subscribe to the list by sending an email to majordomo@vger.kernel.org with
-"subscribe git" in the body. The https://lore.kernel.org/git[archive] of this
-mailing list is available to view in a browser.
-
 [[getting-started]]
 == Getting Started
 
-- 
2.25.0.341.g760bfbb309-goog