[issue24682] Add Quick Start: Communications section to devguide

[Brett Cannon]

Brett Cannon added the comment:

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

--
resolution:  -> out of date
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Ezio Melotti]

Ezio Melotti added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[R. David Murray]

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 :)

--
nosy: +r.david.murray
stage: patch review -> commit review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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
> 
> ___

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[R. David Murray]

R. David Murray added the comment:

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: 
 and .  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 :)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[R. David Murray]

R. David Murray added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[R. David Murray]

Changes by R. David Murray :


--
stage: commit review -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Stephen J. Turnbull]

Stephen J. Turnbull added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Brett Cannon]

Brett Cannon added the comment:

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 =).

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Ezio Melotti]

Ezio Melotti added the comment:

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.

--
stage:  - needs patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Stephen J. Turnbull]

Stephen J. Turnbull added the comment:

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.

--
nosy: +sjt

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Stephen J. Turnbull]

Stephen J. Turnbull added the comment:

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 pytho...@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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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 Issue24689 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!

--
keywords: +needs review -patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

Carol Willing added the comment:

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!

--
keywords: +patch
stage: needs patch - patch review
Added file: http://bugs.python.org/file39988/iss24682.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24682] Add Quick Start: Communications section to devguide

[Carol Willing]

New submission from Carol Willing:

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.

--
assignee: willingc
components: Devguide
messages: 247090
nosy: ezio.melotti, willingc
priority: normal
severity: normal
status: open
title: Add Quick Start: Communications section to devguide
type: enhancement

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue24682
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com