Master documentation plan

[theacodes]

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

[theacodes]

@ncoghlan @ddbeck Please take a look and let me know if you have any concerns? Feel free to include anyone else.

I've dedicating 2-4 hours a week (mostly on Fridays) to this project going forward, so once we're in agreement I can move on this quickly.

[ncoghlan]

I'd suggest splitting out "Interoperability Specifications" as their own document type - they're not "You may want to know this" the way the other discussions are, they're "You probably need to know this if you're a tool developer, otherwise you shouldn't need to care".

The package metadata page and the index API page would then move into that section. I'd suggest leaving the setup() args discussion where it is, though (since that's only an "interoperability spec" for anyone wanting to emulate distutils or setuptools at the Python API level, but is going to be generally useful for users of setuptools and distutils)

Aside from that, the suggested overall structure looks good to me.

[ddbeck]

I'm pretty happy with what I'm seeing here (@ncoghlan's comment included). Thanks!

[theacodes]

I'd suggest splitting out "Interoperability Specifications" as their own document type

Done. Thanks @ncoghlan and @ddbeck. PR to re-arrange things incoming.

[theacodes]

New org structured is merged (yay).

Now to write a better landing page.

[theacodes]

All done. :)