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