From 3acd9350688fefef921ed983c54d0fdaa7ddf09b Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Thu, 25 Jan 2024 12:51:17 -0700
Subject: [PATCH 1/9] Add: readme file tutorial

---
 tutorials/add-readme.md | 211 ++++++++++++++++++++++++++++++++++++++++
 tutorials/intro.md      |  12 ++-
 2 files changed, 221 insertions(+), 2 deletions(-)
 create mode 100644 tutorials/add-readme.md

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
new file mode 100644
index 00000000..04662d08
--- /dev/null
+++ b/tutorials/add-readme.md
@@ -0,0 +1,211 @@
+# Add a README file to your Python package
+
+In the previous lessons you learned:
+
+1. What a Python package is
+2. How to make your code installable and
+3. How to publish your package to (test) PyPI
+
+:::{admonition} Learning objectives
+
+In this lesson you will learn:
+
+1. How to add a **README.md** file to your package.
+2. What the core elements of a **README.md** file are.
+:::
+
+## What is a README file?
+
+The `README.md` file is a markdown file located at the root of your project directory that helps
+a user understand:
+
+- You package's name and what it does
+- The current development "state" of the package (through badges)
+- How to get started with using your package.
+- How to contribute to your package
+- How to cite your package
+
+Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file also will be used to populate your PyPI landing page.
+
+Note that there is no required format for README files. This page simply outlines sections that we suggest you have in your README file.
+
+## Create a README.md file for your package
+
+It's time to add a `README.md` file to your project directory.
+
+### Step 0. Create a README file
+To get started, if you don't already have a README.md file in your project directory, create one.
+
+:::{tip}
+If you created your project directory from
+
+* a GitHub repository online
+* using `hatch init`
+
+Then you may already have a README.MD file in your project directory.
+:::
+
+<!-- If they use hatch init in the very first lesson -
+the readme will already be there-->
+
+### Step 1. Add package badges
+
+At the top of the `README.md` file, add the name of your package.
+
+### Step 2 - add badges to the top of your README file
+
+It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like
+
+* Broken documentation and test builds
+* Versions of your package that are on PyPI and Conda.
+* Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS.
+
+If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI.
+
+If not you can leave the top empty for now and add badges to your README at a later point as they make sense for your package.
+
+### Step 3 - Add a description of what your package does
+
+Below the badges (if you have them), add a section of text
+that provides an easy-to-understand overview of what your
+package does.
+
+* Keep this section short.
+* Try to avoid jargon.
+* Define technical terms that you use to make the description accessible to more people.
+
+Remember that the more people understand what your package does, the more people will use it.
+
+### Step 4 - Add package installation instructions
+
+Next, add instructions that tell users how to install your package.
+
+For example, can they use pip to install your package?
+`pip install packagename`
+
+or conda?
+
+`conda install -c conda-forge packagename`.
+
+If you haven't yet published your package to pypi.org then
+you can skip this section and come back and add these
+instructions later.
+
+### Step 5 - Any additional setup
+
+In some cases, your package users may need to manually
+install other tools in order to use your package. If that
+is the case, be sure to add a section on additional setup
+to your README file.
+
+Here, briefly document (or link to documentation for) any
+additional setup that is required to use your package.
+This might include:
+
+* authentication information if it is applicable to your package.
+* additional tool installations such as GDAL.
+
+:::{note}
+Many packages won't need this section in their README. In that case you can always skip this section!
+:::
+
+
+### Step 6 - Add a get started section
+
+Next add a getting started section that shows how to use your package. This
+section should include a small code chunk that demonstrates importing and using
+some of the functionality in your package.
+
+For the pyosPackage, a short get started demo might look like this:
+
+```python
+>>> from pyospackage.add_numbers import add_num
+>>> add_num(1, 2)
+3
+``````
+
+Or it could simply be a link to a get started tutorial that you have created. If
+you don't have this yet, you can leave it empty for the time being.
+
+This would
+also be a great place to add links to any tutorials that you have created that
+help users understand how to use your package for common workflows.
+
+
+### Step 7 - Community section
+
+The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen either on a platform like GitHub or GitLab.
+
+In the community section, you will add links to your contributing guide
+and `CODE_OF_CONDUCT.md`. You will add a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc).
+
+As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow.
+
+
+
+### Step 8 - Citation & License information
+
+Finally it is important to let users know
+
+1. how to cite your package and
+2. what the license is.
+
+You will create a license file for your package in this lesson.
+
+Your finished `README.md` file should look something like this:
+
+````markdown
+# pyOpenSci-package
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8365068.svg)](https://doi.org/10.5281/zenodo.8365068)
+[![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/115)
+
+## What packagename does
+
+Short description here using non technical language that describes what your package does.
+
+## How to install
+
+<todo - when i add more to the pyos package this can use that readme>
+To install this package... use:
+
+`pip install packagename`
+
+## OPTIONAL - if you have additional setup instructions add them here. if not, skip this section.
+
+## Get started using packagename
+
+Here add a quick code demo showing a user how to use the package after it is installed.
+
+```
+from packagename.module import xmethod
+
+a = xmethod.dosomething(var1, var2)
+
+```
+
+You can also add any links to this section to tutorials in your documentation.
+
+## Community
+
+Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT` file and your development guide. For now this section might be empty. You can go back and fill it in later.
+
+## How to cite packagename
+
+citation information here
+````
+
+## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
+
+It's important to consider the information that a new user or contributor might
+need when creating your `README.md` file. While there is no perfect template,
+above is a set of recommendations as you are just getting started. You may find
+the need for other elements to be added to this file as you further develop your
+package and as a community begins to use your package.
+
+In the [next lesson](add-license-coc), you will add a LICENSE file to
+your Python package. A license file is critical as it tells users
+how they legally can (and can't use your package). It also:
+
+* Builds trust with your users
+* Discourages misuse of your package and associated code
diff --git a/tutorials/intro.md b/tutorials/intro.md
index d820c8e2..b038b431 100644
--- a/tutorials/intro.md
+++ b/tutorials/intro.md
@@ -33,13 +33,21 @@ Get to know Hatch <get-to-know-hatch>
 
 :::{toctree}
 :hidden:
-:caption: Python Packaging 101
+:caption: Create a Python package
 
 What is a Python package? <self>
 Make your code installable <1-installable-code>
 Publish to PyPI <publish-pypi>
 :::
 
+
+:::{toctree}
+:hidden:
+:caption: Project Metadata
+
+Add README file <add-readme>
+:::
+
 :::{admonition} Learning Objectives
 
 This lesson introduces you to the basic components of a Python package.
@@ -301,7 +309,7 @@ publish it in a repository such as **PyPI** or **conda-forge**.
 :::{todo}
 The links below won't work until those lessons (which are written) are published.
 
-Learn [how to publish your package to PyPI in this tutorial.](6-publish-pypi.md)
+Learn [how to publish your package to PyPI in this tutorial.](publish-pypi)
 :::
 
 

From 312540a19385a219cd92e00edbae844023b5ea5f Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Fri, 26 Jan 2024 10:34:37 -0700
Subject: [PATCH 2/9] Fix: the pypi lesson is published - link

---
 tutorials/intro.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/tutorials/intro.md b/tutorials/intro.md
index b038b431..3f698e17 100644
--- a/tutorials/intro.md
+++ b/tutorials/intro.md
@@ -306,12 +306,8 @@ If you want to make your package directly installable without having
 to download the code to your computer locally then you need to
 publish it in a repository such as **PyPI** or **conda-forge**.
 
-:::{todo}
-The links below won't work until those lessons (which are written) are published.
-
-Learn [how to publish your package to PyPI in this tutorial.](publish-pypi)
-:::
 
+You will learn [how to publish your package to PyPI in this tutorial.](publish-pypi)
 
 :::{todo}
 This lesson is also not published - yet but will be reviewed soon.

From 2f9919d309814d9c95c14bfbf69c3b0009581c95 Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Tue, 6 Feb 2024 10:25:18 -0800
Subject: [PATCH 3/9] Fix: edits from @kiersi

Co-authored-by: Jesse Mostipak <jesse.maegan@gmail.com>
---
 tutorials/add-readme.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index 04662d08..02d0bd33 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -3,7 +3,7 @@
 In the previous lessons you learned:
 
 1. What a Python package is
-2. How to make your code installable and
+2. How to make your code installable
 3. How to publish your package to (test) PyPI
 
 :::{admonition} Learning objectives
@@ -56,13 +56,13 @@ At the top of the `README.md` file, add the name of your package.
 
 It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like
 
-* Broken documentation and test builds
+* Broken documentation and test builds.
 * Versions of your package that are on PyPI and Conda.
 * Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS.
 
 If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI.
 
-If not you can leave the top empty for now and add badges to your README at a later point as they make sense for your package.
+If not, you can leave the top empty for now and add badges to your README at a later point as they make sense for your package.
 
 ### Step 3 - Add a description of what your package does
 
@@ -102,8 +102,8 @@ Here, briefly document (or link to documentation for) any
 additional setup that is required to use your package.
 This might include:
 
-* authentication information if it is applicable to your package.
-* additional tool installations such as GDAL.
+* authentication information, if it is applicable to your package.
+* additional tool installations, such as GDAL.
 
 :::{note}
 Many packages won't need this section in their README. In that case you can always skip this section!
@@ -124,7 +124,7 @@ For the pyosPackage, a short get started demo might look like this:
 3
 ``````
 
-Or it could simply be a link to a get started tutorial that you have created. If
+Or it could simply be a link to a getting started tutorial that you have created. If
 you don't have this yet, you can leave it empty for the time being.
 
 This would
@@ -134,7 +134,7 @@ help users understand how to use your package for common workflows.
 
 ### Step 7 - Community section
 
-The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen either on a platform like GitHub or GitLab.
+The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen on a platform like GitHub or GitLab.
 
 In the community section, you will add links to your contributing guide
 and `CODE_OF_CONDUCT.md`. You will add a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc).
@@ -145,7 +145,7 @@ As your package grows you may also have a link to a development guide that contr
 
 ### Step 8 - Citation & License information
 
-Finally it is important to let users know
+Finally it is important to let users know:
 
 1. how to cite your package and
 2. what the license is.

From 877ec8b893a65e5484c50d99251916de33a57aa9 Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Wed, 7 Feb 2024 15:53:04 -0800
Subject: [PATCH 4/9] Update tutorials/add-readme.md

Co-authored-by: Jesse Mostipak <jesse.maegan@gmail.com>
---
 tutorials/add-readme.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index 02d0bd33..afb9579b 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -122,7 +122,6 @@ For the pyosPackage, a short get started demo might look like this:
 >>> from pyospackage.add_numbers import add_num
 >>> add_num(1, 2)
 3
-``````
 
 Or it could simply be a link to a getting started tutorial that you have created. If
 you don't have this yet, you can leave it empty for the time being.

From e5c710ce5970f2abb0e5b18d3dab531c3a26b157 Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Tue, 13 Feb 2024 17:10:55 -0700
Subject: [PATCH 5/9] Fix: Edits from @ucodery

Co-authored-by: Jeremy Paige <ucodery@gmail.com>
---
 tutorials/add-readme.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index afb9579b..2ac7ab88 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -161,12 +161,12 @@ Your finished `README.md` file should look something like this:
 
 ## What packagename does
 
-Short description here using non technical language that describes what your package does.
+Short description here using non-technical language that describes what your package does.
 
 ## How to install
 
 <todo - when i add more to the pyos package this can use that readme>
-To install this package... use:
+To install this package run:
 
 `pip install packagename`
 
@@ -183,11 +183,11 @@ a = xmethod.dosomething(var1, var2)
 
 ```
 
-You can also add any links to this section to tutorials in your documentation.
+You can also add any to tutorials in your documentation here.
 
 ## Community
 
-Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT` file and your development guide. For now this section might be empty. You can go back and fill it in later.
+Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT.md` file and your development guide. For now this section might be empty. You can go back and fill it in later.
 
 ## How to cite packagename
 
@@ -204,7 +204,7 @@ package and as a community begins to use your package.
 
 In the [next lesson](add-license-coc), you will add a LICENSE file to
 your Python package. A license file is critical as it tells users
-how they legally can (and can't use your package). It also:
+how they legally can (and can't) use your package. It also:
 
 * Builds trust with your users
 * Discourages misuse of your package and associated code

From 78a27977f6d9e183961211d6c9796b82f67bdf19 Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Tue, 13 Feb 2024 17:09:58 -0700
Subject: [PATCH 6/9] Fix: edits from review

Fix: edits from review
---
 tutorials/add-readme.md | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index 2ac7ab88..df2b0984 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -48,10 +48,14 @@ Then you may already have a README.MD file in your project directory.
 <!-- If they use hatch init in the very first lesson -
 the readme will already be there-->
 
-### Step 1. Add package badges
+### Step 1. Add the name of your package as the README title
 
 At the top of the `README.md` file, add the name of your package.
 
+if you are using markdown it should be an header 1 tag which is denoted with a single `#` sign.
+
+`# Package-title-here`
+
 ### Step 2 - add badges to the top of your README file
 
 It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like
@@ -113,15 +117,26 @@ Many packages won't need this section in their README. In that case you can alwa
 ### Step 6 - Add a get started section
 
 Next add a getting started section that shows how to use your package. This
-section should include a small code chunk that demonstrates importing and using
+section should include a small code snippet that demonstrates importing and using
 some of the functionality in your package.
 
+:::{admonition} Provide a fully functional code snippet if possible
+:class: important
+
+It is important to try to make the code examples that you provide your users as useful as possible.
+
+Be sure to provide a copy/paste code example that will work as-is when pasted into a Jupyter Notebook or .py file if that is possible.
+
+If there are tokens and other steps needed to run your package, be sure to be clear about what those steps entail.
+:::
+
 For the pyosPackage, a short get started demo might look like this:
 
 ```python
 >>> from pyospackage.add_numbers import add_num
 >>> add_num(1, 2)
 3
+```
 
 Or it could simply be a link to a getting started tutorial that you have created. If
 you don't have this yet, you can leave it empty for the time being.
@@ -176,10 +191,10 @@ To install this package run:
 
 Here add a quick code demo showing a user how to use the package after it is installed.
 
-```
-from packagename.module import xmethod
-
-a = xmethod.dosomething(var1, var2)
+```python
+>>> from pyospackage.add_numbers import add_num
+>>> add_num(1, 2)
+3
 
 ```
 

From 9f5729a8fb980878bb2c7d4aa8e1a03cc9634e9c Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Wed, 14 Feb 2024 17:35:25 -0700
Subject: [PATCH 7/9] Fix: remove license from readme and add citation

---
 tutorials/add-readme.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index df2b0984..22054d08 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -157,14 +157,20 @@ As your package grows you may also have a link to a development guide that contr
 
 
 
-### Step 8 - Citation & License information
+### Step 8 - Citation information
 
-Finally it is important to let users know:
+Finally it is important to let users know how to cite your package.
+You can communication citation information in a few different ways.
 
-1. how to cite your package and
-2. what the license is.
+You can use a tool such as zenodo to create a DOI and associated citation
+information for your package if it is hosted on a platform such as
+GitHub. [Check out this short tutorial that covers setting that up.](https://coderefinery.github.io/github-without-command-line/doi/)
 
-You will create a license file for your package in this lesson.
+Alternatively if you send your package through a peer review process such
+as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html), then you can all get a cross-ref DOI through our partnership
+with the Journal of Open Source Software.
+
+## The finished README file
 
 Your finished `README.md` file should look something like this:
 

From f13d330b7ed92d1b90c49dc8c37b6b067655570b Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Wed, 21 Feb 2024 13:14:39 -0700
Subject: [PATCH 8/9] Fix: edits from @ucodery

Co-authored-by: Jeremy Paige <ucodery@gmail.com>
---
 tutorials/add-readme.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index 22054d08..1e3f68a8 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -52,7 +52,7 @@ the readme will already be there-->
 
 At the top of the `README.md` file, add the name of your package.
 
-if you are using markdown it should be an header 1 tag which is denoted with a single `#` sign.
+If you are using markdown it should be a header 1 tag which is denoted with a single `#` sign.
 
 `# Package-title-here`
 
@@ -160,14 +160,14 @@ As your package grows you may also have a link to a development guide that contr
 ### Step 8 - Citation information
 
 Finally it is important to let users know how to cite your package.
-You can communication citation information in a few different ways.
+You can communicate citation information in a few different ways.
 
 You can use a tool such as zenodo to create a DOI and associated citation
 information for your package if it is hosted on a platform such as
 GitHub. [Check out this short tutorial that covers setting that up.](https://coderefinery.github.io/github-without-command-line/doi/)
 
 Alternatively if you send your package through a peer review process such
-as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html), then you can all get a cross-ref DOI through our partnership
+as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html), then you can get a cross-ref DOI through our partnership
 with the Journal of Open Source Software.
 
 ## The finished README file
@@ -204,7 +204,7 @@ Here add a quick code demo showing a user how to use the package after it is ins
 
 ```
 
-You can also add any to tutorials in your documentation here.
+You can also add any links to tutorials in your documentation here.
 
 ## Community
 

From 419ab9e63eb2950a79e870cc073b3d8f71ee44da Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah@pyopensci.org>
Date: Wed, 21 Feb 2024 13:15:03 -0700
Subject: [PATCH 9/9] Fix: more review edits

---
 tutorials/add-readme.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
index 1e3f68a8..732b8e32 100644
--- a/tutorials/add-readme.md
+++ b/tutorials/add-readme.md
@@ -19,7 +19,8 @@ In this lesson you will learn:
 The `README.md` file is a markdown file located at the root of your project directory that helps
 a user understand:
 
-- You package's name and what it does
+- You package's name
+- What the package does. Your README file should clearly state the problem(s) that your software is designed to solve and its target audience.
 - The current development "state" of the package (through badges)
 - How to get started with using your package.
 - How to contribute to your package
@@ -175,25 +176,25 @@ with the Journal of Open Source Software.
 Your finished `README.md` file should look something like this:
 
 ````markdown
-# pyOpenSci-package
+# pyosPackage
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8365068.svg)](https://doi.org/10.5281/zenodo.8365068)
 [![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/115)
 
-## What packagename does
+## What pyosPackage does
 
 Short description here using non-technical language that describes what your package does.
 
-## How to install
+## How to install pyosPackage
 
 <todo - when i add more to the pyos package this can use that readme>
 To install this package run:
 
-`pip install packagename`
+`pip install pyosPackage`
 
 ## OPTIONAL - if you have additional setup instructions add them here. if not, skip this section.
 
-## Get started using packagename
+## Get started using pyosPackage
 
 Here add a quick code demo showing a user how to use the package after it is installed.
 
@@ -210,10 +211,9 @@ You can also add any links to tutorials in your documentation here.
 
 Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT.md` file and your development guide. For now this section might be empty. You can go back and fill it in later.
 
-## How to cite packagename
+## How to cite pyosPackage
 
 citation information here
-````
 
 ## <i class="fa-solid fa-hands-bubbles"></i> Wrap up