Fix: edits from review

Author: lwasser

index.md

@@ -1,5 +1,11 @@
 # pyOpenSci Python Open Source Package Development Guide
 
+```{toctree}
+:hidden:
+:caption: Tutorials
+Tutorials  <tutorials/intro>
+```
+
 ```{toctree}
 :hidden:
 :caption: Documentation

tutorials/1-installable-code.md

@@ -1,8 +1,21 @@
 # Make your Python code pip installable
 
-The first step in creating a Python package based on code that you
-have is to make that code pip installable. You will learn how to make
-your code pip installable in this lesson.
+In the previous lesson, you learned about both what a Python package is. You also learned about the [benefits of creating a Python
+package](tutorials/intro.html#why-create-a-python-package) including:
+
+* Being able to easily reuse in multiple workflows on your computer
+* Being able to share your code with others who may find the functionality useful.
+* Being able to better organize code that needs to be reused.
+
+
+The first step in creating a Python package is turning that
+code into a Python package that is pip installable.
+The package that you create in this lesson will have
+the bare minimum elements that you need to install a package.
+
+In upcoming lessons you will learn how to:
+* add a **README** file to support community use of your package
+* add package metadata in a **pyproject.toml** file to support publication to PyPI
 
 <!--
 TODO: is it clear where to add commands? bash vs. python console
@@ -11,11 +24,12 @@ Bash vs zsh is different
 does this work on windows and mac? i know it works on mac/linux
 -->
 
-:::{figure-md} code-to-script
+:::{figure-md} code-to-python-package
+
+<img src="../images/tutorials/code-to-python-package.png" alt="Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." width="700px">
 
-<img src="../images/tutorials/code-to-script-diagram.png" alt="Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." width="700px">
+A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer.
 
-A basic installable package needs a few things: code, a specific package structure and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer.
 :::
 
 :::{admonition} Learning Objectives
@@ -33,7 +47,7 @@ environment. You are welcome to use any environment manager that you choose.
 
 * [If you need guidance creating a Python environment, review this lesson](extras/1-create-environment.md) which walks you through creating an environment using both `venv` and `conda`.
 * If you aren't sure which environment manager to use and
-you are a scientist, we suggest that you use `conda`.
+you are a scientist, we suggest that you use `conda`, particularly if you are working with any sort of spatial data.
 :::
 
 ## Make your package installable

tutorials/intro.md

@@ -0,0 +1,12 @@
+# Python packaging 101
+
+When we merge PR 1 this file will be updated with
+full content. please ignore for now it's a placeholder for the toctree
+
+:::{toctree}
+:hidden:
+:caption: Python Packaging 101
+
+What is a Python package? <self>
+Make your code pip installable <1-installable-code>
+:::