This is the master plan for restructuring this guide. This issue's description will be edited as discussions occur. It's the plan of record for what the end state is and what steps we will take to get to the end state. This is proposed as a minimal set of changes to improve these docs and encourage contributions, once we have this foundation we can build on this to improve even further. Specifically, the work started by @ddbeck for new tutorials will be significantly easier after this structure is in place.

Documentation Types

This guide will consist of 3 distinct documentation types:

• tutorials are focused on teaching the reader new concepts by accomplishing a goal. They are opinionated step-by-step guides. They do not include extraneous warnings or information. example
• guides are focused on accomplishing a specific task and can assume some level of pre-requisite knowledge.. These are similar to tutorials, but have a narrow and clear focus and can provide lots of caveats and additional information as needed. They may also discuss multiple approaches to accomplishing the task. example
• discussions are focused on understanding and information. These explore a specific topic without a specific goal in mind. example

We may revisit and add additional documentation types as needed.

Documentation plan

This is the set of docs that we want to provide, organized in the final toctree.

1. Landing page
2. Tutorials
   1. Installing packages
   2. Creating & publishing packages
3. Guides (items and titles in this section are most likely to change)
   1. Installing packaging tools with Linux package managers
   2. Installing scientific packages
   3. Multi-version installs
   4. Single-sourcing the package version
   5. Supporting multiple python versions
   6. Packaging binary extensions
   7. Building wheels for Windows using AppVeyor
   8. Packaging namespace packages
   9. Creating and discovering plugins
   10. Index mirrors & caches
   11. Hosting your own index
   12. Deploying applications
4. Discussions
   1. install-requires vs requirements.txt
   2. pip vs easy_install
   3. wheel vs egg
   4. setup() arguments
5. Specifications
   1. Package metadata
   2. Package index interfaces
6. Glossary
7. How to get help
8. How to get involved

These pages will be moved to other projects:

1. Key projects will be moved into pypa.io

Steps to get there

• Get agreement on this plan.
• Migrate to new theme. (Switch to pypa theme #305)
• Add a script to track broken deep links. (Add script to check for broken deep links #315)
• Write new landing page, describing documentation types and linking into tutorials.
• Move existing pages into sub-folders based on the above toctree . (Re-organize existing documentation into new structure. #318)
• Drop old docs out of the source tree. (Re-organize existing documentation into new structure. #318)

Once we're there

After this work is done, we should be able to more easily divide and conquer handling new tutorials, addressing issues, and revising existing content. My next task will be to work on revising the two top-level tutorials and possibly breaking them up according to @ddbeck's guide (and taking a page out of Django's book).