Fix: edits to first two lessons for flow

lwasser · lwasser · commit 9d3ea276753c · 2024-03-01T13:01:20.000-07:00
diff --git a/tutorials/add-license-coc.md b/tutorials/add-license-coc.md
@@ -16,14 +16,14 @@ In this lesson you will learn:
 3. How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`.
 :::
 
-## What is a license and why is it important?
+## What is a license?
 
 A license contains legal language about how users can use and reuse your software. To set the LICENSE for your project, you:
 
 1. create LICENSE file in your project directory that specifies the license that you choose for your package and
 2. reference that file in your pyproject.toml data where metadata are set.
 
-By adding the LICENSE file to your pyproject.toml file, the LICENSE will be included in your package's metadata which is used to populate your package's PyPI landing page. It is also used in your GitHub repository (see image below).
+By adding the LICENSE file to your pyproject.toml file, the LICENSE will be included in your package's metadata which is used to populate your package's PyPI landing page. The LICENSE is also used in your GitHub repository's landing page interface.
 
 ### What license should you use?
 
@@ -51,14 +51,13 @@ are placed in the root of the project directory using standard naming convention
 :::
 
 
-## How to add a LICENSE file to your package repository
+### How to add a LICENSE file to your package directory
 
 There are several ways to add a LICENSE file:
 
 1. When you create a new repository on GitHub, it will ask you if you wish to add a `LICENSE` file at that time. If you select yes, it will create the file for you.
 2. You can add a license through the GitHub gui following the [<i class="fa-brands fa-github"></i> instructions here](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository).
 3. You can add the file manually like we are doing in this lesson.
-4. Or, if you are using a tool such as Hatch, it will add a LICENSE file for you.
 
 :::{tip}
 If you completed the past lessons including
@@ -71,11 +70,11 @@ then you already have a **LICENSE** file containing text for the MIT license in
 If you don't yet have a **LICENSE** file in your directory, then continue reading.
 :::
 
-### Add a LICENSE to your existing GitHub repository
+### How to add a LICENSE to your package - the manual way
 
 If you don't already have a LICENSE file, and you are not yet using a platform such as GitHub or GitLab, then you can create a license file by
 
-1. Create a new file called LICENSE. If you are using a shell you can use:
+1. Create a new file called LICENSE. If you are using shell you can type:
 
 ```
 # Create a license file in your shell
@@ -86,6 +85,7 @@ If you don't already have a LICENSE file, and you are not yet using a platform s
 2. Select permissive license
 3. It will suggest that you use the [MIT license](https://choosealicense.com/licenses/mit/).
 4. Copy the license text that it provides into your LICENSE file that you created above.
+5. Save your file. You're all done!
 
 :::{admonition} An overview of LICENSES in the scientific Python ecosystem
 :class: note
@@ -131,29 +131,43 @@ GitHub landing page.
 :::::
 ::::::
 
+Now you know how to add a LICENSE to your project. Next, you'll learn
+about the `CODE_OF_CONDUCT.md` file and how to add it to your
+package directory.
+
 (add-coc)=
-## Add a CODE_OF_CONDUCT file to your repository
+## What is a code of conduct file?
 
-Now that you have added a LICENSE to your project, you are ready to add a `CODE_OF_CONDUCT.md` to your package directory. The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the LICENSE file,.
+A `CODE_OF_CONDUCT` file is used to establish guidelines for how people in your community interact.
 
-A `CODE_OF_CONDUCT` file is critical to supporting your community as it
+This file is critical to supporting your community as it
 grows. The `CODE_OF_CONDUCT`:
 
 1. Establishes guidelines for how users and contributors interact with each other and you in your software repository.
 2. Identifies negative behaviors that you don't want in your interactions.
 
 You can use your code of conduct as a tool that can be referenced when moderating challenging conversations.
 
+### What to put in your code of conduct file
+
 If you are unsure of what language to add to your `CODE_OF_CONDUCT`
 file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place.
 
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](#)
 
-### Add your CODE_OF_CONDUCT file
+The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the LICENSE file.
+
+### How to add a CODE_OF_CONDUCT file to your package directory
+
+- Add a `CODE_OF_CONDUCT.md` file to the root of your repository if it doesn't already exist.
 
-- Add a `CODE_OF_CONDUCT.md` file to your repository if it doesn't
-  already exist.
-- Visit the [contributor covenant website](https://www.contributor-covenant.org/) and add [the markdown version of their code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your `CODE_OF_CONDUCT.md` file.
+```bash
+> touch CODE_OF_CONDUCT.md
+```
+
+- Visit the [contributor covenant website](https://www.contributor-covenant.org/) and add [the markdown version of their code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your `CODE_OF_CONDUCT.md` file. Read the text closely to ensure you both understand it and also agree with its contents!
+
+That's it - you've now added a code of conduct to your package directory.
 
 :::{admonition} Additional Code of Conduct resources
 :class: note
@@ -173,11 +187,11 @@ In this lesson and the [last lesson](add-readme), you have added a:
 
 These are fundamental files needed for every scientific Python package
 repository. These files help users understand how to use your package and
-interact with package maintainers. In the upcoming
-lessons, you will:
+interact with package maintainers.
+
+In the upcoming lessons, you will:
 
-- [Flesh out your `pyproject.toml` file](pyproject-toml) to support building
-  and publishing your package on PyPI.
+- [Add more metadata to your `pyproject.toml` file](pyproject-toml) to support building and publishing your package on PyPI.
 - Publish a new version of your Python package to (Test) PyPI to preview the
   updated metadata landing page.
 
diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
@@ -2,9 +2,10 @@
 
 In the previous lessons you learned:
 
-1. What a Python package is
-2. How to make your code installable
-3. How to publish your package to (test) PyPI
+1. [What a Python package is](intro.md)
+2. [How to make your code installable](1-installable-code)
+3. [How to publish your package to (test) PyPI](publish-pypi.md)
+4. [How to publish your package to conda-forge](publish-conda-forge.md)
 
 :::{admonition} Learning objectives
 
@@ -26,15 +27,17 @@ a user understand:
 - 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.
+Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file is also 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.
+Note that there is no specific content structure for README files.
+However, this tutorial outlines the sections that we suggest that you
+include 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
+### 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}
@@ -49,27 +52,27 @@ 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 the name of your package as the README title
+### 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 a header 1 tag which is denoted with a single `#` sign.
+If you are using markdown it should be a header 1 (H1) tag which is denoted with a single `#` sign.
 
 `# Package-title-here`
 
-### Step 2 - add badges to the top of your README file
+### 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
+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.
+If not, you can leave the top empty for now and add badges to your README at a later point as they make sense.
 
-### Step 3 - Add a description of what your package does
+### 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
@@ -81,7 +84,7 @@ package does.
 
 Remember that the more people understand what your package does, the more people will use it.
 
-### Step 4 - Add package installation instructions
+### Step 4: Add package installation instructions
 
 Next, add instructions that tell users how to install your package.
 
@@ -96,7 +99,7 @@ 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
+### 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
@@ -111,14 +114,14 @@ This might include:
 * 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!
+Many packages won't need an additional setup section in their README.
+In that case you can always skip this section.
 :::
 
 
-### Step 6 - Add a get started 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 snippet that demonstrates importing and using
+Next add a get-started section. Within this section, add a small code example that demonstrates importing and using
 some of the functionality in your package.
 
 :::{admonition} Provide a fully functional code snippet if possible
@@ -128,7 +131,7 @@ It is important to try to make the code examples that you provide your users as
 
 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.
+If there are tokens and other steps needed to run your package, be sure to be clear about what those steps are.
 :::
 
 For the pyosPackage, a short get started demo might look like this:
@@ -143,22 +146,28 @@ Or it could simply be a link to a getting started tutorial that you have created
 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
+also be a great place to add links to tutorials that
 help users understand how to use your package for common workflows.
 
 
-### Step 7 - Community section
+### 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 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).
+and `CODE_OF_CONDUCT.md`. You will create 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.
+As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow. The development guide
+outlines how to perform maintenance tasks such as:
 
+* running tests
+* making package releases
+* building documentation
+* and more.
 
 
-### Step 8 - Citation information
+
+### Step 8: Citation information
 
 Finally it is important to let users know how to cite your package.
 You can communicate citation information in a few different ways.
@@ -168,8 +177,8 @@ 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 get a cross-ref DOI through our partnership
-with the Journal of Open Source Software.
+as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html). After being accepted by pyOpenSci, if your package is in scope, you can be accepted by the Journal of Open Source Software and get a cross-ref DOI through [our partnership with the Journal of Open Source Software.](https://www.pyopensci.org/about-peer-review/index.html)
+
 
 ## The finished README file
 
