Add a Quick Start: Communications section to devguide (or Q S: Community Interaction) as discussed on python-dev mailing list today.

The Quick Start: Communications section should be brief, link to other sections in the devguide, and give contributor's guidance about mailing list usage. It is possible that new sections of the devguide will be created to provide additional detail and be referenced by the Quick Start: Communications section. 

Rename existing devguide/#quick-start 'Quick Start' to 'Quick Start: Code Development'. Thanks Terry Reedy for the name suggestions.

I would also like to see a short section (perhaps in the form of a FAQ) that could be linked whenever someone asks for Python help on python-dev/python-ideas, or proposes an idea on python-dev, or "misuses" the lists in a similar fashion.
These could then be linked with a short message such as "Python-dev is about the development of CPython, not for general Python help. See devguide/communication.html#faq-asking-for-general-python-help".
As for the "Quick Start" I'm not exactly sure what you want to put in it, but I'm not sure whether it should be added alongside the main quick start and if it should be called a quick start (I don't think people ask themselves "I want to communicate, where do I start?").
I think expanding /devguide/communication.html (and/or devguide/help.html), adding a list of guidelines at the top and description/faqs of the MLs should be enough.  A link in the main page (perhaps even in the "coding" quick start) could also be added.

Ezio, thanks for the suggestions :D 

To clarify, the new Quick Start will be: 
- brief; 
- contain links to additional communication/community interaction info in the devguide; 
- guide a new contributor (or remind others) to information about ways to communicate effectively to maximize productivity as a contributor.

My goal with the new Quick Start is to give new developers simple steps to onboard as constructive and productive contributors. Basically, key steps to onboarding such as: 1. mailing lists, 2. Issue tracker, 3. expectations, 4. questions.

After I take a close look at the entire devguide and related resources, I will upload a patch for the new Quick Start which should add clarity. We can iterate the patch as needed to make sure that the info is helpful and relevant for contributors.

Here's the patch for adding the `Quick Start: Community workflow` section to the devguide.

I made a few other minor edits to the index page (replacing beginner/advanced wording for starter/additional) since docs and testing are important. While docs and testing are great starting points for new developers, docs and testing have their own advanced nuances as well. :D

Ezio, Thanks for the earlier suggestions. Please do make any additional suggestions to improve this patch. I wanted to get it up so you had a better sense of my approach.

I expect that there will be other devguide changes to come after this. Perhaps as Ezio suggested a more detailed mailing list section in help.rst, but I think that those can be addressed in a separate issue.

Thanks!

If the mailing list code of conduct is to be fleshed out, Paul Moore's post is a good place to start IMO: https://mail.python.org/pipermail/python-dev/2015-July/140872.html.

I tend to disagree with Ezio about a FAQ for general questions.  A pointer to appropriate alternatives for off-topic posts in the Mailman listinfo descriptions of the various list (which can be copied into the devguide, or linked from there) will be sufficient for people who actually read such things before posting.

OTOH, once there already is a misdirected post, I feel it's appropriate to say "This post is off-topic here because this list is for development of Python itself, not developing applications with Python.  Posts like yours are ignored  by almost all participants.  You will get help (possibly better than you could get on this list) on Python-X@python.org."  Adding a pointer to a FAQ which just repeats the same thing is browbeating IMO.  It's not like we don't have several people who have macros to say the above (and more politely than I did) who typically respond within hours to off-topic posts.  What more could a FAQ say?  Of course this needs to be on-list so that the poster (who usually is a little feckless rather than deliberately abusive) doesn't get spammed, and so that the multiple volunteers who handle these posts don't duplicate each other.

I personally would like to see a guideline to participants that if they want to offer advice on the question itself to people, that they do so off-list.  Whatever one's opinion on the utility of offering advice in response to an off-topic post, such advice is as off-topic as the question that elicits it.

Thanks Stephen for the additional links and suggestions.

I would like to keep this issue focused on the Quick Start section added in the patch. 

I've opened Issue<24689> to focus on "tips for effective online communication". I have referenced the comments here and suggested an approach in the issue.

I want to keep momentum moving forward on improving the devguide and feel keeping issues well scoped will help us do that. If someone has the time to review this patch, I would appreciate the help. Thanks!

The patch overall LGTM, although it's hard to read in a browser due to the lack of code review integration with Rietveld (time to go email some people to keep the code process moving forward =).

Ezio, Brett, Stephen: Would one of you be able to merge this? Thanks.

I just reviewed again, and I agree it's ready for merge.  I don't see any immediate need to add more.

Unfortunately, I'm not a committer.

Stephen, Thanks for reviewing to make sure it's still current. I appreciate it.

Core devs: Please merge and we'll close this one. Thanks.

Carol: as part of requesting a commit you can set the stage to 'commit review' (I've done that for this one) and that may lead to at least a couple of us noticing it where we wouldn't otherwise :)

R. David Murray wrote:
>
> R. David Murray added the comment:
>
> Carol: as part of requesting a commit you can set the stage to 'commit 
> review' (I've done that for this one) and that may lead to at least a 
> couple of us noticing it where we wouldn't otherwise :)
>

Thank you David for the tip and for changing the stage. I didn't realize 
that I could select 'commit review' for my own patch. :-)

>
> ----------
> nosy: +r.david.murray
> stage: patch review -> commit review
>
> _______________________________________
> Python tracker<report@bugs.python.org>
> <http://bugs.python.org/issue24682>
> _______________________________________

Well, you got agreement from Stephen :)  But you are right, I had overlooked the fact that this was your patch.  I also just gave Stephen Developer privs on the tracker so he can do it in the future on issues he thinks are ready.

All that said, I don't think there's anything wrong with moving one's own patch to commit review if you really think it is ready, if you have had other eyes on it.

Looking over this...I'm -0.

I really don't like the organization of the front page of the developers guide.  The idea of a "quick start" section is fine, but is it appropriate? (I'm talking about the code quick start)  The first pages of the document, to my mind, should be either a collection of almost-bare links to the most-often-referenced material, or a simple introduction, or (what I expect and am continually annoyed by not finding) a well organized table of contents.

I do not recall ever finding anything I wanted in the document without going to the table of contents.  Of course, I'm not a newbie...but it is a little hard for me to see how the intro material actually helps the newbie, either.  I am especially struck by the statement in the "contributing" section that says it is recommended the articles be read in the order listed...if so, why isn't that the table of contents?  In other words, the document should be organized in the way the material is best read.

On the other hand, I'm not offering to rewrite it, so take my comments for what they are worth in that regard :)

Coming back to adding this section in particular: It feels like it is trying to be that "short introduction" I mentioned above, without quite succeeding in being one.  It seems to have a mix of goals: welcoming, pointing to newbie resources, and talking about community communication norms.  I really don't know what I'd do with this information if I were a newbie, and it doesn't seem to answer enough questions about how to contribute to justify being the first "quick start" thing the newbie reads.  That form of presentation, especially in the context of the succeeding section that shows how to get set up, make it sound like these are action items (as does the "quick start" in the title)...but none of them are sequential action items; they are, rather, informational links and discussions of norms.

So, I'd propose rewriting it to take the form of an introduction.  Perhaps something like this:

-----------------------------------------------------------------
Welcome to the Python development community.  This guide collects the accumulated knowledge and wisdom of the Python community around how the Python language and the CPython implementation (the "reference implementation") of the Python language are developed and maintained. It strives to be a comprehensive resource for contributing to Python, and the definitive collection (insofar as possible) of the "corporate knowledge and culture" of the Python community.  The guide contains information that new, developing, and experienced contributors have found helpful. It is maintained by the same community that maintains Python.

The Python community places a high value on collegiality and mutual support.  We strive to be welcoming to everyone.  Inevitably there will be disagreements, and occasionally these can get heated.  A big part of being a contributor is communicating respectfully with others in the community.  We all make mistakes, though, so being able to apologize and move on is a very helpful skill.  The best technique for avoiding problems is to stay focused on the issue at hand: how to solve whatever problem is under discussion.  That often means reaching a compromise, something the Python community is pretty good at doing.

If you are new to Python development, in addition to reading this guide you will want to take advantage of the community's contributor mentorship program: <python mentors> and <core-mentorship>.  There you can get direct advice from experienced contributors to help smooth the process of contributing.  As the adage goes, the only stupid question is the question that isn't asked.  So come ask us.
--------------------------------------------------------------------

I haven't included the links to other resources.  It seems to me that that list of resources deserves its own section, in which case a link to it could be added to the above intro.

Now, this is just my opinion...if everyone else likes the "quick start" approach I'm not going to object :)

David, I love the three paragraph intro. It captures the essence of the dev guide usage from newcomers to the project to experienced core devs. I really like the second paragraph and how it suggests focusing on the issue at hand. Thanks, and I will take these three suggested paragraphs and rework the patch.

I'll use the three paragraphs as an intro, circular file the quickstart, and rework some of the remaining content into its own section(s).

I respect how you like a quality Table of Contents when looking for information. Alternatively, other folks use search extensively to find information, and search gives a different, less linear walk through the document. So I think it is reasonable to err on the side of a quality uncluttered Table of Contents.

However, I also do think that those that are new to the project are looking for a bit more guidance. Though I concur that the guidance does not need to be in a quickstart; though it should be in an easily discoverable place.  Quickstarts are common on other open source projects so new contributors will likely look for one (or something similar). What new contributors are looking for are brief pathways (i.e. a few steps toward productivity) specific to documentation, testing, issue triaging, etc. Whether called pathways or a quickstart isn't critical, what is important is guiding those that need more assistance and those that don't have the time privilege to read the devguide in its entirety.

Thanks for the suggestions. I'll make another pass at it. :D

FWIW when I added the quickstart (#13228), its main target wasn't newbies, but devs that already have experience with other open source projects and want to contribute to CPython.
These people just need to know where is the repo and the bug tracker, how to build Python, and how to run the tests.

OTOH, the quickstart is also useful to newbies as it provides a concise list of steps and additional links that cover them in greater detail.

So there are at least two targets here:
* experienced devs: they know what they want and they are looking for specific steps that will bring them there.  They also tend to skip wordy sections (so no important info should be hidden in a wall of text).
* newbies: they might not know what they want and/or what to do and need more guidance in a more verbose fashion.

I would leave the quickstart as is, and possibly add a separate introduction as R. David suggested.

Moved to https://github.com/python/devguide/issues/8