[Distutils] New PyPUG Tutorials

[Marcus Smith]

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


So, I'm back to post the initial proposal as mentioned above.

The proposal was put together by Daniel Beck (http://www.danieldbeck.com),
one of the writers Nicole (from the Warehouse team) was able to rally with
her call for volunteers [1].

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.

As work proceeds, it will take place as PRs to the develop branch of the
PyPUG (https://github.com/pypa/python-packaging-user-guide/), 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.

Both Daniel and Nicole are now subscribed to distutils-sig, and can respond
to any questions, concerns, or feedback.

Here's the proposal, as quoted from an email from Daniel:

-----------------------------------------

Scope
---------
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.

Audience
-------------
I get the impression that these are the major audience groups we want to
help with the guide:

- 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
- Python users with intermediate experience who want to make and distribute
a package for the first time
- Python users with more experience who need a refresher or want to
understand what the "one way to do it" is right now
- Python users with lots of experience who want to take on some advanced or
specialized packaging task

Outline
----------
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.

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

1. About this guide
2. Getting help
3. Quick references (i.e., five minute tutorials)
  a. Installing a package
  b. Making a package
  c. Publish a package on PyPI
4. Intro to Packaging*
  a. Who is this for?
  b. Prereqs (making sure Python, etc. are working)
  c. What's a package?
  d. Where do packages come from?
  e. Installing a package for the first time
  f. Using a virtualenv
  g. Making a package for the first time
  h. Publishing your first package
5. The Packaging Ecosystem (concept docs)
  a. Overview of tools
  b. Developing packages
  c. Distributing packages
  d. Indices and caches
6. Practices and patterns (task docs)
  a. Making packages
  b. Publishing packages
  c. Using packages
7. History and legacy of packaging
  a. that whole distutils->setuptools->distribute->setuptools saga
  b. history of PyPA
  c. eggs vs wheels
  d. easy_install vs pip
  e. cheeseshop vs warehouse
8. Contributing to this guide
  a. Style guide

* 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.

Timeline
------------
Here's my current perspective on how quickly we can move on these things:

- In the next few days: contacting volunteers to let them know that things
are happening soon (Nicole)
- 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)
- In the next two weeks: start opening issues and inviting volunteers to
start writing
- By the end of November: most, if not all, existing content could be
reorganized into a new outline
- By mid-December: have publishable versions of the new tutorials
- By the end of January: potentially finished?


[1] https://github.com/pypa/warehouse/issues/729
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20151115/3af329ee/attachment.html>