nsidc · nsidc-service-admin · Sep 26, 2022 · Sep 26, 2022 · Sep 26, 2022 · Sep 26, 2022
diff --git a/README.md b/README.md
@@ -31,7 +31,11 @@ After running either of these scripts, you can open the file
 
 ## Troubleshooting
 
-TODO
+### ReadTheDocs build status is not showing up in GitHub
+
+If you're sure, following RTD's instructions, that the relevant GitHub permissions are
+correct, sometimes the only way to fix this problem is to delete and recreate the
+project in RTD.
 
 
 ## License

diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,92 @@
+# Make the structure/order of the materials more clear
+
+* How should people use these training materials? In what order?
+
+* How should NSIDC deliver these trainings to users? (e.g. tiny bites? 1 tutorial + 1
+discussion in a session?)
+
+* Should there be a way of indicating materials that you can get by without? e.g. you
+don't _need_ to understand the history as a DAG but it may help some learners.
+
+
+## Guided learning
+
+The most attention-drawing thing a user sees when they first load the page should be an
+outline of the materials suggesting where to start and how to progress. The sidebar can
+provide similar quick-navigation once the user has left the front page.
+
+
+### Discussion: What is Git / what is Git for?
+
+* Who is Git for? What can Git do for me?
+* Why should I use Git and not Google Docs / MS Office?
+* When should I not use Git?
+
+
+### Tutorial 1a: Intro to Git through GitHub GUI
+
+* Creating repositories with the GUI
+* Contributing to repositories with the GUI
+* Reviewing changes in GitHub GUI
+
+NOTE: Using GitHub GUI features first, or CLI first?
+
+
+### Tutorial 1b: Intro to Git at the CLI / `git` commands
+
+* Cloning a repository from GitHub / `init` on local computer
+* Adding changes, committing
+* Log, diffing
+* Authenticating to push
+* Pushing
+
+NOTE: How  to make "pushing" part easiest? All methods seem non-trivial and require
+install of something (e.g. `openssh` not necessarily installed). [GH
+docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line)
+describe using GitHub CLI, using the `git` program with a Personal Access Token, using
+Git Credential Manager, or using SSH keys.
+
+
+### Discussion: Understanding Git's history with graph theory
+
+* Git's history is a Directed Acyclic Graph
+
+NOTE: Should this be before the branching/merging tutorial or after?
+
+
+### Tutorial 2: Branching and merging at the CLI
+
+* What do branches do for me?
+* What are conflicts? How do I resolve conflicts?
+
+
+### Discussion: Merge strategies
+
+* Fast-forward
+* Squash
+
+NOTE: Integrate this information into branching/merging tutorial?
+
+
+### Tutorial 3: Pull requests
+
+* How do I open a PR?
+* What do I do after I open a pull request?
+* What do I do after I'm asked to review a PR?
+
+
+### Tutorial 4: Forks / upstreams
+
+* What does it mean to fork?
+* How to fork?
+* Remotes and having multiple (e.g. `origin` and `upstream`)
+
+
+## Reference
+
+* Dedicated section for workflow-focused cheat sheets? The "How-to" section currently
+  contains that material.
+* Cheat sheets paired with tutorial contents?
+* A "style guide" or "symbology" page? Would be useful to document re-usable elements
+  like BitBucket/GitLab compatibility notes, authors' notes, warnings, format standards
+  for images/captions, etc.
diff --git a/doc/home.rst b/doc/home.rst
@@ -11,22 +11,37 @@ NSIDC Git Training
     :alt: Git logo
 
 
-.. include:: what-to-expect.md
-    :parser: myst_parser.sphinx_
+Ensure you have the right software installed: :doc:`/reference/prerequisites`
+
8000

+The following is the recommended order to tackle this material:
+
+* **Discussion**: :doc:`./discussion/about-git`
+
+* **Tutorial**: Basic usage. Choose one based on your preferred interface:
+    * [TODO] Intro to using Git through GitHub GUI
+    * :doc:`/tutorial/1b-intro-to-git-cli/index`
+
+* Working with others using Git:
 
+    * **Discussion**: [TODO] Understanding Git history through Graph Theory
 
-How to use these materials
---------------------------
+    * **Tutorial**: [TODO] Branching and merging with Git CLI
 
-- Ensure you have the right things installed: :doc:`/reference/prerequisites`
+    * **Discussion**: [TODO] Merge strategies
 
-- Learn about what Git is for: :doc:`./discussion/about-git`
+    * **Tutorial**: [TODO] Pull requests
 
-- Do the beginner tutorial: :doc:`/tutorial/working-locally/index`
+    * **Tutorial**: [TODO] Forks
 
-- See the "How To"s on the left nav-bar. They can be used as a Git cheat sheet!
 
-- Selected reference materials:
-    - :doc:`./reference/glossary`
-    - :doc:`./reference/best-practices-and-good-habits`
-    - :doc:`./reference/external-resources`
+
+* See the "How To"s on the left nav-bar. They can be used as a Git cheat sheet!
+
+* Selected reference materials:
+    * :doc:`./reference/glossary`
+    * :doc:`./reference/best-practices-and-good-habits`
+    * :doc:`./reference/external-resources`
+
+
+.. include:: what-to-expect.md
+    :parser: myst_parser.sphinx_
diff --git a/doc/index.rst b/doc/index.rst
@@ -18,7 +18,7 @@
     :numbered:
     :hidden:
 
-    tutorial/working-locally/index.rst
+    tutorial/1b-intro-to-git-cli/index.rst
     tutorial/working-with-others/index.rst
 
 

diff --git a/...l/working-locally/01-create-a-new-repo.md → ...-intro-to-git-cli/01-create-a-new-repo.md b/...l/working-locally/01-create-a-new-repo.md → ...-intro-to-git-cli/01-create-a-new-repo.md
diff --git a/...working-locally/02-create-some-content.md → ...ntro-to-git-cli/02-create-some-content.md b/...working-locally/02-create-some-content.md → ...ntro-to-git-cli/02-create-some-content.md
diff --git a/...torial/working-locally/03-first-commit.md → ...al/1b-intro-to-git-cli/03-first-commit.md b/...torial/working-locally/03-first-commit.md → ...al/1b-intro-to-git-cli/03-first-commit.md
diff --git a/...torial/working-locally/04-more-commits.md → ...al/1b-intro-to-git-cli/04-more-commits.md b/...torial/working-locally/04-more-commits.md → ...al/1b-intro-to-git-cli/04-more-commits.md
diff --git a/...utorial/working-locally/05-time-travel.md → ...ial/1b-intro-to-git-cli/05-time-travel.md b/...utorial/working-locally/05-time-travel.md → ...ial/1b-intro-to-git-cli/05-time-travel.md
diff --git a/doc/tutorial/working-locally/06-tag.md → doc/tutorial/1b-intro-to-git-cli/06-tag.md b/doc/tutorial/working-locally/06-tag.md → doc/tutorial/1b-intro-to-git-cli/06-tag.md
diff --git a/doc/tutorial/working-locally/07-branch.md → ...tutorial/1b-intro-to-git-cli/07-branch.md b/doc/tutorial/working-locally/07-branch.md → ...tutorial/1b-intro-to-git-cli/07-branch.md
diff --git a/doc/tutorial/working-locally/08-fix-main.md → ...torial/1b-intro-to-git-cli/08-fix-main.md b/doc/tutorial/working-locally/08-fix-main.md → ...torial/1b-intro-to-git-cli/08-fix-main.md
diff --git a/doc/tutorial/working-locally/09-diff.md → doc/tutorial/1b-intro-to-git-cli/09-diff.md b/doc/tutorial/working-locally/09-diff.md → doc/tutorial/1b-intro-to-git-cli/09-diff.md
diff --git a/doc/tutorial/working-locally/10-merge.md → doc/tutorial/1b-intro-to-git-cli/10-merge.md b/doc/tutorial/working-locally/10-merge.md → doc/tutorial/1b-intro-to-git-cli/10-merge.md
diff --git a/...tutorial/working-locally/99-conclusion.md → ...rial/1b-intro-to-git-cli/99-conclusion.md b/...tutorial/working-locally/99-conclusion.md → ...rial/1b-intro-to-git-cli/99-conclusion.md
diff --git a/doc/tutorial/working-locally/index.rst → doc/tutorial/1b-intro-to-git-cli/index.rst b/doc/tutorial/working-locally/index.rst → doc/tutorial/1b-intro-to-git-cli/index.rst
@@ -1,5 +1,5 @@
-Working with Git locally
-========================
+Intro to Git through CLI commands
+=================================
 
 In this tutorial, you will create a Git repository, make and track several changes,
 create and work on independent {term}`branches<Branch>`, and merge work from different
@@ -15,8 +15,8 @@ files and directories in your operating system of choice.
 
 
 .. toctree::
-    :name: Tutorial #1 steps
-    :caption: Tutorial #1 steps
+    :name: Tutorial #1b steps
+    :caption: Tutorial #1b steps
     :maxdepth: 1
     :glob:
 

diff --git a/doc/tutorial/working-with-others/index.rst b/doc/tutorial/working-with-others/index.rst
@@ -16,7 +16,7 @@ commits from Bitbucket and :code:`pull` your main branch up-to-date with those c
 
 
 Before starting this tutorial, you should have completed the first tutorial
-:doc:`/tutorial/working-locally/index`.
+:doc:`/tutorial/1b-intro-to-git-cli/index`.
 
 .. note::
     If you're looking for quick help with specific tasks, check out the How-Tos instead!