<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><br></div><div>To have the most success, the writers will certainly need feedback from subject matter experts, so the process will include 2 stages where we specifically ask for feedback from PyPA-Dev and Distutils-Sig:  1) To validate the initial proposal that covers the scope of the changes, and 2) to review the actual PRs to PyPUG for accuracy, when it's time for merging.   I'll post again with more details as those stages occur.</div></div></blockquote><div><br></div><div><br></div><div><div>So, I'm back to post the initial proposal as mentioned above.  </div><div><br></div><div>The proposal was put together by Daniel Beck (<a href="http://www.danieldbeck.com">http://www.danieldbeck.com</a>), one of the writers Nicole (from the Warehouse team) was able to rally with her call for volunteers [1].</div><div><br></div><div>It includes a *tentative* new outline, but keep in mind that however it turns out, we will maintain redirects for the current critical links, like the tool recommendations page, and the two current tutorials.</div><div><br></div><div>As work proceeds, it will take place as PRs to the develop branch of the PyPUG (<a href="https://github.com/pypa/python-packaging-user-guide/">https://github.com/pypa/python-packaging-user-guide/</a>), so people can follow along and help in the technical review process.    When the final product is deemed worthy and ready, there will be a final call for review before the merge of develop back into master.</div><div><br></div><div>Both Daniel and Nicole are now subscribed to distutils-sig, and can respond to any questions, concerns, or feedback.</div><div><br></div><div>Here's the proposal, as quoted from an email from Daniel:</div><div><br></div><div>-----------------------------------------</div><div><br></div><div>Scope</div><div>---------</div><div>The guide is meant to answer this question: "How do Python, packages, and packaging tools fit together?" The guide's not to meant to replace tools' docs; rather, it's to show when and how these tools and other artifacts work as an ecosystem.</div><div><br></div><div>Audience</div><div>-------------</div><div>I get the impression that these are the major audience groups we want to help with the guide:</div><div><br></div><div>- Python users who are at an 'advanced beginner' level (e.g., know how to import from the standard library, but want to learn to install a third-party package for the first time</div><div>- Python users with intermediate experience who want to make and distribute a package for the first time</div><div>- Python users with more experience who need a refresher or want to understand what the "one way to do it" is right now</div><div>- Python users with lots of experience who want to take on some advanced or specialized packaging task</div><div><br></div><div>Outline</div><div>----------</div><div>I sketched out a gross outline for the guide. This is not complete, sometimes speculative, and certainly subject to change, but I wanted to give you an overall picture of how I imagine the guide could look when we've had some time to work on this. </div><div><br></div><div>Again, because the existing content is so good, I don't expect much, if anything, will be deleted—so just because it's not listed here doesn't mean anything. Rather, I expect that stuff will be easier to find. :-)</div><div><br></div><div>1. About this guide</div><div>2. Getting help</div><div>3. Quick references (i.e., five minute tutorials)</div><div>  a. Installing a package</div><div>  b. Making a package</div><div>  c. Publish a package on PyPI</div><div>4. Intro to Packaging*</div><div>  a. Who is this for?</div><div>  b. Prereqs (making sure Python, etc. are working)</div><div>  c. What's a package?</div><div>  d. Where do packages come from?</div><div>  e. Installing a package for the first time</div><div>  f. Using a virtualenv</div><div>  g. Making a package for the first time</div><div>  h. Publishing your first package</div><div>5. The Packaging Ecosystem (concept docs)</div><div>  a. Overview of tools</div><div>  b. Developing packages</div><div>  c. Distributing packages</div><div>  d. Indices and caches</div><div>6. Practices and patterns (task docs)</div><div>  a. Making packages</div><div>  b. Publishing packages</div><div>  c. Using packages</div><div>7. History and legacy of packaging</div><div>  a. that whole distutils->setuptools->distribute->setuptools saga</div><div>  b. history of PyPA</div><div>  c. eggs vs wheels</div><div>  d. easy_install vs pip</div><div>  e. cheeseshop vs warehouse</div><div>8. Contributing to this guide</div><div>  a. Style guide </div><div><br></div><div>* This is the only part that I think functions as a continuous unit meant to be read from start to end. I'm imagining something that would work as, for example, a lesson plan for a PyLadies workshop. For the rest of the guide, I want to work with the expectation that every page is a landing page.</div><div><br></div><div>Timeline</div><div>------------</div><div>Here's my current perspective on how quickly we can move on these things:</div><div><br></div><div>- In the next few days: contacting volunteers to let them know that things are happening soon (Nicole)</div><div>- In the 7 or 8 days: decide on workflow questions (Nicole and Marcus), amend project roles (Nicole and Marcus), and ask for distutils-sig approval (Marcus)</div><div>- In the next two weeks: start opening issues and inviting volunteers to start writing</div><div>- By the end of November: most, if not all, existing content could be reorganized into a new outline</div><div>- By mid-December: have publishable versions of the new tutorials</div><div>- By the end of January: potentially finished?</div><div><br></div><div><br></div><div>[1] <a href="https://github.com/pypa/warehouse/issues/729">https://github.com/pypa/warehouse/issues/729</a></div></div></div></div></div>