pypa · willingc · Jul 20, 2019 · Jul 20, 2019 · Jul 20, 2019 · Jul 20, 2019
diff --git a/authors.txt b/authors.txt
@@ -2,6 +2,7 @@ Alex J. Burke
 Brett Cannon
 C\. Titus Brown
 Carl Meyer
+Carol Willing
 Daniel Holth
 Kevin Teague
 Jean-Paul Calderone

diff --git a/source/basics.rst b/source/basics.rst
@@ -0,0 +1,49 @@
+======================
+Basics of Installation
+======================
+
+.. Editors, see notes at the bottom of the document for maintenance info.
+
+.. contents:: Contents
+   :local:
+
+Jargon
+------
+
+- System Python
+- Selected Python
+- Environments (None, virtual, conda)
+- Package manager/tool (pipenv, pip, conda, miniconda, others)
+- Advanced installation cases
+
+Installation using PyPA Tools
+-----------------------------
+
+
+Third Party Installation Tools
+------------------------------
+
+Best Practices Checklist
+------------------------
+
+- Review the installation documentation for the package
+- Install the package by following the installation documentation
+- Most packages will be installed with pipenv or pip.
+- [Science and Data Science Packages] The installation instructions may include
+  references to conda and conda-forge. Follow those instructions.
+
+Wrap up
+-------
+
+
+
+.. Editing notes:
+
+   This document targets a novice audience especially scientists who may
+   not have a computer development background. It's expected
+   that most developers finding this document will have experience installing
+   applications and apps, but may not have installed a Python package before
+   or be familiar with the command line.
+
+   For specific how-to information refer to the documentation of the desired
+   package for installation.
diff --git a/source/discussions/index.rst b/source/discussions/index.rst
@@ -1,14 +1,21 @@
-Discussions
-###########
+Concepts
+########
 
-**Discussions** are focused on providing comprehensive information about a
-specific topic. If you're just trying to get stuff done, see
-:doc:`/guides/index`.
+The **Concepts** section discusses fundamental information about specific
+topics.
+
+The goals of this section include providing background information, describing
+important technical concepts, and highlighting usage tradeoffs.
+
+Contents include:
 
 .. toctree::
    :maxdepth: 1
 
-   deploying-python-applications
-   pip-vs-easy-install
    install-requires-vs-requirements
+   pip-vs-easy-install
    wheel-vs-egg
+   deploying-python-applications
+
+Alternatively, if you're trying to get a specific task done, see
+:doc:`/guides/index`.
diff --git a/source/tutorials/creating-documentation.rst → source/guides/creating-documentation.rst b/source/tutorials/creating-documentation.rst → source/guides/creating-documentation.rst
diff --git a/source/guides/index.rst b/source/guides/index.rst
@@ -1,9 +1,10 @@
-Guides
-######
+Tasks
+#####
 
-**Guides** are focused on accomplishing a specific task and assume that you are
-already familiar with the basics of Python packaging. If you're looking for an
-introduction to packaging, see :doc:`/tutorials/index`.
+**Tasks** guides focus on accomplishing specific tasks.
+
+The guides in this Tasks section assume that you are already familiar with the
+basics of Python packaging. Contents include:
 
 .. toctree::
    :maxdepth: 1
@@ -28,4 +29,7 @@ introduction to packaging, see :doc:`/tutorials/index`.
    hosting-your-own-index
    migrating-to-pypi-org
    using-testpypi
+   creating-documentation
    making-a-pypi-friendly-readme
+
+If you're looking for an introduction to packaging, see :doc:`/tutorials/index`.
diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
@@ -7,12 +7,24 @@ Installing scientific packages
 .. contents:: Contents
    :local:
 
+Overview
+--------
 
 Scientific software tends to have more complex dependencies than most, and
 it will often have multiple build options to take advantage of different
 kinds of hardware, or to interoperate with different pieces of external
 software.
 
+Prerequisites
+-------------
+
+A basic understanding of the Scientific Python stack as well as installation
+of packages using tools such as pip or conda and using hosting repositories
+like PyPI and conda-forge.
+
+Complexity, NumPy, and SciPy
+----------------------------
+
 In particular, `NumPy <http://www.numpy.org/>`__, which provides the basis
 for most of the software in the `scientific Python stack
 <http://www.scipy.org/stackspec.html#stackspec>`__ can be configured
@@ -31,18 +43,25 @@ libraries (or any other Python libraries that require a compilation environment
 to install from source and don't provide pre-built wheel files on PyPI).
 
 
-Building from source
---------------------
+Building and installing from source
+-----------------------------------
 
 The same complexity which makes it difficult to distribute NumPy (and many
 of the projects that depend on it) as wheel files also make them difficult
 to build from source yourself. However, for intrepid folks that are willing
 to spend the time wrangling compilers and linkers for both C and FORTRAN,
 building from source is always an option.
 
+Installation options by operating system
+----------------------------------------
+
+Scientific packages may use multiple programming languages. In addition,
+the use of different operating systems increases the complexity of installation.
+Therefore, the selection of installation tool and method will often depend on
+several factors including those already mentioned.
 
 Linux distribution packages
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For Linux users, the system package manager will often have pre-compiled
 versions of various pieces of scientific software, including NumPy and
@@ -54,7 +73,7 @@ installed into the system Python when using virtual environments).
 
 
 Windows installers
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Many Python projects that don't (or can't) currently publish wheel files at
 least publish Windows installers, either on PyPI or on their project
@@ -83,7 +102,7 @@ convert a Windows `bdist_wininst` installer to a wheel.
 .. _mac-os-x-installers-and-package-managers:
 
 macOS installers and package managers
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Similar to the situation on Windows, many projects (including NumPy) publish
 macOS installers that are compatible with the macOS CPython binaries
@@ -105,27 +124,14 @@ end users in an easy to use and update format.
 Some of these distributions may not be compatible with the standard ``pip``
 and ``virtualenv`` based toolchain.
 
-Spack
-------
-`Spack <https://github.com/LLNL/spack/>`_ is a flexible package manager
-designed to support multiple versions, configurations, platforms, and compilers.
-It was built to support the needs of large supercomputing centers and scientific
-application teams, who must often build software many different ways.
-Spack is not limited to Python; it can install packages for ``C``, ``C++``,
-``Fortran``, ``R``, and other languages.  It is non-destructive; installing
-a new version of one package does not break existing installations, so many
-configurations can coexist on the same system.
-
-Spack offers a simple but powerful syntax that allows users to specify
-versions and configuration options concisely. Package files are written in
-pure Python, and they are templated so that it is easy to swap compilers,
-dependency implementations (like MPI), versions, and build options with a single
-package file.  Spack also generates *module* files so that packages can
-be loaded and unloaded from the user's environment.
+Third-party package managers
+----------------------------
 
+Often a third-party package manager, maintained by groups other than PyPA, may
+be an expedient solution for installing scientific and data science packages.
 
 The conda cross-platform package manager
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `Anaconda <https://www.anaconda.com/download/>`_ is a Python distribution
 published by Anaconda, Inc. It is a stable collection of Open Source
@@ -145,3 +151,51 @@ written in Python, but is Python-agnostic. Conda manages Python itself as a
 package, so that `conda update python` is possible, in contrast to pip, which
 only manages Python packages. Conda is available in Anaconda and Miniconda (an
 easy-to-install download with just Python and conda).
+
+Miniconda
+~~~~~~~~~
+
+A lighter-weight option for conda installs and often using conda-forge as the
+preferred channel.
+
+Spack
+~~~~~
+
+`Spack <https://github.com/LLNL/spack/>`_ is a flexible package manager
+designed to support multiple versions, configurations, platforms, and compilers.
+It was built to support the needs of large supercomputing centers and scientific
+application teams, who must often build software many different ways.
+Spack is not limited to Python; it can install packages for ``C``, ``C++``,
+``Fortran``, ``R``, and other languages.  It is non-destructive; installing
+a new version of one package does not break existing installations, so many
+configurations can coexist on the same system.
+
+Spack offers a simple but powerful syntax that allows users to specify
+versions and configuration options concisely. Package files are written in
+pure Python, and they are templated so that it is easy to swap compilers,
+dependency implementations (like MPI), versions, and build options with a single
+package file.  Spack also generates *module* files so that packages can
+be loaded and unloaded from the user's environment.
+
+Conda-forge
+-----------
+
+Maintained and tested scientific packages by the conda-forge community. A
+good source for finding up-to-date builds for package installation.
+
+DockerHub
+---------
+
+Docker and other container technologies are used within the sciences to spin
+up a predetermined container of packages. This often can be an aid to
+reproducibility of results.
+
+What's next
+-----------
+
+A wise recommendation for installing Scientific packages would be to follow
+the installation recommendations provided in the package's documentation.
+Another practical next step for users who are new to installing Python Scientific
+packages would be to consult a recent tutorial or talk from a prior PyCon,
+SciPy, or PyData conference which describes the current state of installing
+scientific packages and tools.
diff --git a/source/index.rst b/source/index.rst
@@ -11,6 +11,7 @@ Python Packaging User Guide
    :hidden:
 
    overview
+   basics
    tutorials/index
    guides/index
    discussions/index
@@ -32,26 +33,64 @@ happily accept any :doc:`contributions and feedback <contribute>`. 😊
 .. _Python Packaging Authority: https://pypa.io
 
 
+Navigating the User Guide
+=========================
+
+The *Python Packaging User Guide* is organized into several sections:
+
++------------------------------+----------------------------------------------------------+
+| Section                      | Description                                              |
++------------------------------+----------------------------------------------------------+
+| :doc:`tutorials/index`       | Introduce packaging concepts through opinionated,        |
+|                              | step-by-step guides, such as *Installing Packages*       |
+|                              | and *Packaging Projects*.                                |
++------------------------------+----------------------------------------------------------+
+| :doc:`guides/index`          | Focus on accomplishing a specific task, such as          |
+|                              | *Making a PyPI friendly README* and *Installing*         |
+|                              | *Scientific Packages*.                                   |
++------------------------------+----------------------------------------------------------+
+| :doc:`discussions/index`     | Provide comprehensive information about a specific topic |
+|                              | such as *install_requires vs requirements files* and     |
+|                              | *Wheel vs Egg*.                                          |
++------------------------------+----------------------------------------------------------+
+| :doc:`specifications/index`  | Document interoperability and standards, such as         |
+|                              | *Entry points specification*                             |
++------------------------------+----------------------------------------------------------+
+| :doc:`key_projects`          | Highlights PyPA maintained projects and mentions notable |
+|                              | third-party maintained projects.                         |
++------------------------------+----------------------------------------------------------+
+| :doc:`glossary`              | Define unfamiliar terms or jargon                        |
++------------------------------+----------------------------------------------------------+
+
+
 Get started
 ===========
 
-Essential tools and concepts for working within the Python
-development ecosystem are covered in our :doc:`tutorials/index` section:
+Many readers will find the :doc:`tutorials/index` section a good starting place
+to learn more about Python packaging. It provides step-by-step information about
+the essential tools and concepts of installing and packaging Python projects:
+
+* :doc:`tutorial on Installing Packages <tutorials/installing-packages>`
+* :doc:`tutorial on Managing Application Dependencies <tutorials/managing-dependencies>`
+  in a version controlled project
+* :doc:`tutorial on Packaging and Distributing <tutorials/packaging-projects>`
+  your projects
+
+The :doc:`Basics of Installation <basics>` discusses the methods of
+installing a Python package for different use cases, such as web, scientific
+applications, devops, and more. New developers are encouraged to read this
+section before the :doc:`tutorial on Installing Packages <tutorials/installing-packages>`.
 
-* to learn how to install packages, see the
-  :doc:`tutorial on installing packages <tutorials/installing-packages>`.
-* to learn how to manage dependencies in a version controlled project, see the
-  :doc:`tutorial on managing application dependencies <tutorials/managing-dependencies>`.
-* to learn how to package and distribute your projects, see the
-  :doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`
-* to get an overview of packaging options for Python libraries and
-  applications, see the :doc:`Overview of Python Packaging <overview>`.
+Intermediate to advanced Python developers interested in creating a Python
+package will benefit from reviewing the :doc:`Overview of Python Packaging <overview>`
+and its guidance on planning development for packaging.
 
 
 Learn more
 ==========
 
-Beyond our :doc:`tutorials/index`, this guide has several other resources:
+Beyond our :doc:`tutorials/index`, this User Guide has several resource
+sections with topical and in-depth information:
 
 * the :doc:`guides/index` section for walk throughs, such as
   :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`

diff --git a/source/overview.rst b/source/overview.rst
@@ -1,6 +1,6 @@
-===================================
-An Overview of Packaging for Python
-===================================
+================================
+Overview of Packaging for Python
+================================
 
 .. Editors, see notes at the bottom of the document for maintenance info.
 

diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
@@ -11,4 +11,3 @@ topics, see :doc:`/guides/index`.
     installing-packages
     managing-dependencies
     packaging-projects
-    creating-documentation