docs: 📝 clarify using and next steps guides for non-rostools uses

docs/guide/next-steps.qmd

@@ -2,15 +2,108 @@
 title: "Next steps"
 description: |
   Tasks to do in your workshop after applying the template to it.
-order: 4
+order: 3
 ---
 
 While most of the post-applying steps are listed in the created `TODO.md` file
 within the workshop, this documents some more details for these steps. Use this
 guide alongside the `TODO.md` to complete those tasks. For example, one of the
-first tasks is to start having Git track the workshop with `git init`.
+first tasks is to start having Git track the workshop with `git init`. There are
+two sets of tasks: required and optional.
 
-## Setting up pre-commit hooks
+## Required
+
+These next steps are required in order to actually set up the workshop's
+website.
+
+### Setting up a GitHub repository
+
+One of the main purposes of this template and using these tools and workflows
+from it is to make the material public and create a website for the workshop. In
+order to do that, it needs to go on some type of work
+
+These series of steps are only necessary if you are using this template for a
+repository that is part of rostools. If you want a quick way of putting your
+workshop on GitHub, you can use the `gh` command line tool to upload the
+workshop to GitHub:
+
+```bash {filename="Terminal"}
+gh repo create --source=. --public --push USER/REPO
+```
+
+::: callout-tip
+If you're using the template to create a workshop within the rostools GitHub
+organization, use the instructions below that use a custom command line tool. We
+built this tool to help us manage our many GitHub repositories across several
+projects. While it's useful for us, it isn't designed or built in a way that
+makes it easy for others to use (yet).
+
+For setting up a GitHub repository for the created workshop that will be part of
+rostools, you'll need to install the Seedcase Project's (a "sibling"
+organisation) internal tool [`spaid`](https://github.com/seedcase-project/spaid)
+and use the following commands to run the next setup steps:
+
+```bash {filename="Terminal"}
+spaid_gh_create_repo_from_local -h
+spaid_gh_set_repo_settings -h
+spaid_gh_ruleset_basic_protect_main -h
+spaid_gh_ruleset_require_pr -h
+```
+
+Some configuration *may* be needed after copying this template to a new
+repository, including configuration external to the repository. Some GitHub
+workflows require installing GitHub Apps, for greater security purposes and
+easier administration when managing multiple repositories. The [security
+section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens)
+in our [Guidebook](https://guidebook.seedcase-project.org/) provides some
+instructions on how to set up GitHub Apps, secrets, and variables. In the case
+of rostools, these have already been set up. The specific workflows in this
+template that require this additional setup are:
+
+- The workflow `.github/workflows/release.yml` requires the
+  [auto-release-token](https://github.com/apps/auto-release-token) GitHub App,
+  which is specific to the Seedcase Project but usable within rostools. This
+  workflow requires that the GitHub secret `UPDATE_VERSION_TOKEN` and a variable
+  called `UPDATE_VERSION_APP_ID` are connected to the repository.
+- The workflow `.github/workflows/add-to-project.yml` requires the
+  [add-to-board-token](https://github.com/apps/add-to-board-token) GitHub App
+  (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` secret and the
+  `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. These will already be
+  set up to work in all public repositories on rostools.
+:::
+
+## Connecting to hosting services
+
+If you use this template to make a website hosted on
+[Netlify](https://www.netlify.com/), you need to connect the GitHub repository
+to Netlify. The Quarto documentation has an [excellent
+guide](https://quarto.org/docs/publishing/netlify.html) on how to do this. It
+includes configuring Netlify to host the website and adding the
+[`NETLIFY_AUTH_TOKEN`](https://quarto.org/docs/publishing/netlify.html#netlify-credentials)
+secret to the GitHub repository (or ideally at the organization level).
+
+::: callout-note
+Since all rostools workshops use Netlify, any workshops created for rostools
+already has `NETLIFY_AUTH_TOKEN` connected to any public repository on rostools.
+:::
+
+For hosting on [GitHub Pages](https://pages.github.com/), it's a bit easier to
+set up than Netlify. The Quarto documentation again has a
+[guide](https://quarto.org/docs/publishing/github-pages.html) on how to do this.
+Before you can host on GitHub Pages, you need to use Quarto to set things up for
+you, by running the following command:
+
+```bash {filename="Terminal"}
+quarto publish github-pages
+```
+
+## Optional
+
+These optional next steps are very helpful for developing and refining
+workshops. However, they are a bit more advanced than is required, so only do
+them if you feel comfortable enough with them.
+
+### Setting up pre-commit hooks
 
 [Pre-commit hooks](https://pre-commit.com/) are scripts that run when committing
 changes to a Git repository. They are incredibly useful for enforcing coding
@@ -33,7 +126,7 @@ including pull requests, which will ensure that the code is checked for basic
 issues. It will also keep the pre-commit hooks updated by creating a pull
 request whenever newer versions of the hooks are available.
 
-## Adding the Quarto theme
+### Adding the Quarto theme
 
 ::: callout-warning
 This step is only necessary if you are using this template for a repository that
@@ -69,76 +162,7 @@ project:
 format: rostools-theme-html
 ```
 
-## Setting up a GitHub repository
-
-::: callout-warning
-These series of steps are only necessary if you are using this template for a
-repository that is part of rostools. If you want a quick way of putting your
-workshop on GitHub, you can use the `gh` command line tool to upload the
-workshop to GitHub:
-
-```bash {filename="Terminal"}
-gh repo create {{ github_repo_spec }} --source=. --public`
-```
-:::
-
-We have a custom command line tool that we developed to help manage GitHub
-repositories for rostools repositories. While it's useful for us, it isn't
-designed or build in a way that makes it easy for others to use.
-
-For setting up a GitHub repository for the created workshop that will be part of
-rostools, you'll need to install the Seedcase Project's (a "sibling"
-organisation) internal tool [`spaid`](https://github.com/seedcase-project/spaid)
-and use the following commands to run the next setup steps:
-
-```bash {filename="Terminal"}
-spaid_gh_create_repo_from_local -h
-spaid_gh_set_repo_settings -h
-spaid_gh_ruleset_basic_protect_main -h
-spaid_gh_ruleset_require_pr -h
-```
-
-Some configuration is needed after copying this template to a new repository,
-including configuration external to the repository. Some GitHub workflows
-require installing GitHub Apps, for greater security purposes and easier
-administration when managing multiple repositories. The [security
-section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens)
-in our [Guidebook](https://guidebook.seedcase-project.org/) provides some
-instructions on how to set up GitHub Apps, secrets, and variables. Ideally the
-secrets and variables should be set up in the organization settings. The
-specific workflows in this template that require this additional setup are:
-
-- The workflow `.github/workflows/release.yml` requires the
-  [auto-release-token](https://github.com/apps/auto-release-token) GitHub App,
-  which is specific to the Seedcase Project but usable within rostools, as well
-  as a creating a GitHub secret called `UPDATE_VERSION_TOKEN` and a variable
-  called `UPDATE_VERSION_APP_ID` that has the App ID.
-- The workflow `.github/workflows/add-to-project.yml` requires the
-  [add-to-board-token](https://github.com/apps/add-to-board-token) GitHub App
-  (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` secret and the
-  `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID.
-
-## Connecting to hosting services
-
-If you use this template to make a website hosted on
-[Netlify](https://www.netlify.com/), you need to connect the GitHub repository
-to Netlify. The Quarto documentation has an [excellent
-guide](https://quarto.org/docs/publishing/netlify.html) on how to do this. It
-includes configuring Netlify to host the website and adding the
-[`NETLIFY_AUTH_TOKEN`](https://quarto.org/docs/publishing/netlify.html#netlify-credentials)
-secret to the GitHub repository (or ideally at the organization level).
-
-For hosting on [GitHub Pages](https://pages.github.com/), it's a bit easier to
-set up than Netlify. The Quarto documentation again has a
-[guide](https://quarto.org/docs/publishing/github-pages.html) on how to do this.
-Before you can host on GitHub Pages, you need to use Quarto to set things up for
-you, by running the following command:
-
-```bash {filename="Terminal"}
-quarto publish github-pages
-```
-
-## Auto-releasing to Zenodo
+### Auto-releasing to Zenodo
 
 ::: callout-warning
 This step is only necessary if you are using this template for a repository that
@@ -148,9 +172,10 @@ different workshop, you can use this section to guide you to setting it up for
 your workshop.
 :::
 
-If you create a release on GitHub, either manually or through a GitHub workflow,
-you can have that release automatically create a record on Zenodo, which is a
-service that allows you to archive workshops and create a DOI for it.
+If you create a release on GitHub, either manually or through a workflow, you
+can connect Zenodo to create records of any releases. Zenodo is a service that
+allows you to archive content and create a DOI for it, such as the workshop's
+material.
 
 GitHub and Zenodo have an integration that, when set up, will automatically
 create a [Zenodo record](https://help.zenodo.org/docs/deposit/about-records/)
@@ -162,12 +187,12 @@ workshop. Connecting GitHub to Zenodo is very easy, check out Zenodo's
 [guide](https://help.zenodo.org/docs/github/archive-software/github-upload/) on
 it.
 
-## Setting up GoatCounter
+### Setting up GoatCounter
 
-s If you want to use GoatCounter for website visitor tracking, you need to
-create a GoatCounter account and set up a new site for your website. Adding a
-new site is very easy. Go into the "Settings" after logging into your account.
-Under "Sites", click "Add new site" and fill in the form with your website's
-unique name. You can use the auto-filled name in the
-`includes/site-counter.html` file, which has the format of "orgname-reponame" or
-modify your own.
+If you want to use [GoatCounter](https://www.goatcounter.com) for website
+visitor tracking (no personal data, so no GDPR issues), you need to create a
+GoatCounter account and set up a new site for your website. Adding a new site is
+very easy. Go into the "Settings" after logging into your account. Under
+"Sites", click "Add new site" and fill in the form with your website's unique
+name. You can use the auto-filled name in the `includes/site-counter.html` file,
+which has the format of "orgname-reponame" or modify your own.

docs/guide/updating.qmd

@@ -3,7 +3,7 @@ title: "Updating a workshop"
 description: |
   A guide on updating a workshop that uses this template with the latest changes
   from the template.
-order: 3
+order: 4
 ---
 
 One of the biggest strengths of Copier is that it allows you to easily update

docs/guide/using.qmd

@@ -13,29 +13,44 @@ apply it to an existing workshop.
 
 You can use this template to create a new workshop with a standard set of files
 and folders, as well as all the features and configurations to make it easier to
-build your workshop smoothly and effectively. First, open a terminal and run the
-following command:
+build your workshop smoothly and effectively. First, open a terminal and change
+your working directory to a location you want to create the new workshop
+project, e.g. `Documents/`:
 
 ```bash {filename="Terminal"}
-uvx copier copy gh:rostools/template-workshop path/to/WORKSHOP-NAME
+cd Documents
 ```
 
-The `copy` command uses the template on GitHub (`gh:`) at the
-`rostools/template-workshop` location. The `path/to/` is the location where
-you'd like the new workshop to be created and `WORKSHOP-NAME` is the name you
+Next, copy and paste the following command, replacing the `WORKSHOP-NAME` with
+the name you want for your new workshop. The `WORKSHOP-NAME` is the name you
 want to give for the new workshop's directory and (ideally) the GitHub
 repository for the workshop. The name should be something short and meaningful,
 ideally lowercase, with `-` instead of spaces, and no special characters.
 
+```bash {filename="Terminal"}
+uvx copier copy gh:rostools/template-workshop WORKSHOP-NAME
+```
+
+The `copy` command uses the template on GitHub (`gh:`) at the
+`rostools/template-workshop` location.
+
 ## Applying to an existing workshop
 
 If you want to use this template on an existing workshop, you can use the `copy`
 command of `copier` just like above to apply the template to the existing
 workshop. This will add all the template's files and configurations to the
-existing workshop.
+existing workshop. First, open a terminal and move your working directory to the
+existing workshop's directory:
+
+```bash {filename="Terminal"}
+cd Documents/EXISTING-WORKSHOP
+```
+
+Next, copy and paste the command below. The `.` means "use the template in the
+current directory":
 
 ```bash {filename="Terminal"}
-uvx copier copy gh:rostools/template-workshop path/to/EXISTING-WORKSHOP
+uvx copier copy gh:rostools/template-workshop .
 ```
 
 See the comment above in the "Creating a new workshop" section about the naming