[tracking] new tutorials and other revisions

[ddbeck]

This issue is to track work on writing new, introductory tutorials for the guide, and other activities that are part of an effort to expand and revise the guide. See this thread from the distutils-sig for more details about this project. Work on these tutorials will (at least initially) take place on the develop branch.

I am inviting the group of volunteers to use this issue to see what other issues are available and to use this as a place for general questions and help (i.e., questions that are not issue-specific), to minimize noise on other issues and the creation of new issues.

If you'd like to contribute to these sections, please see the (to be) linked issues for details. Additionally, please review the developing guide to contributing. If you start work on an issue, please consider saying so on the relevant issue, so others don't duplicate your work. Thanks!

Outline

Broadly, the new intro to packaging tutorials have the following outline:

1. Who is this for?
2. Prerequisites
3. What's a package?
4. Where do packages come from?
5. Install your first package
6. Use a virtual environment
7. Make your first package
8. Publish your first package

Issues will soon be created to address each section specifically; the outline above will link to each section's issue.

Bite size tasks

• Add build instructions to the README #207: Add build instructions to the README

Extra style notes

The intro to packaging tutorials have some extra style considerations on top of that of the guide generally:

• In contrast to more task-focused writing, the tutorials are meant to build fundamental packaging skills, rather than resolve a specific problem. With that in mind, try to invite readers to learn to do something without regard for its specific applications. So instead of something like "Read this section if you want to share a package…" try "After you complete this section, you'll be able to share a package…"

[souravsingh]

I would like to work on the first two parts of the tutorial.

[ddbeck]

@souravsingh That's great! I would suggest picking one to begin with and, as you make progress, mention that you're working on it in the section-specific issue (so others don't duplicate your work). Let me know if you have any questions. Thanks!

[thatdocslady]

I'll be happy to help with content reviews (proofreading, editing) and overall structure, unfortunately I don't have enough bandwidth at the moment to write content from scratch :-( feel free to assign any content that needs review to me :-)

[souravsingh]

Thanks for the help @thatdocslady

[alexwlchan]

Like thatdocslady, I'm happy to take on review tasks if it's useful, but I can't promise any original content (things are all a bit up-in-the-air at the moment).

[ddbeck]

@thatdocslady @alexwlchan thank you both for volunteering! As sections become stable, I'll definitely call on you to be a new set of eyes.