refactor from user test feedback

app/cmd/embeds/walkthrough/01-example-unit/00-hello-world.md

@@ -19,9 +19,13 @@ learn preview .
 ```
 to see your update. You may preview individual files by specifying them for faster previewing. This is the part of the recommended workflow when developing new content and modifying existing content.
 
-## TODO explain preview cohort
+## Your Preview Cohort
 
-If you just ran `learn preview .` from the root of the walkthrough directory, you'll notice new content in the side bar. This content is rendered from the walkthrough files:
+If you look at the URL Learn created where your content can be found, you'll notice a cohort id which belongs to you! Learn cohorts are where instructors and students come together to learn subjects and montior progress, but this cohort is just for your curriculum development. Content you preview will always attach itself to your preview cohort and remain there until your next preview.
+
+The urls are built using the file names in the project, so each time you preview the same project you can simply refresh the browser to see changes you have made.
+
+If you just ran `learn preview .` from the root of the walkthrough directory, you might notice new content in the side bar. This content is produced from the walkthrough files:
 ```
 ├── 01-example-unit
 │   ├── 00-hello-world.md
@@ -32,15 +36,26 @@ If you just ran `learn preview .` from the root of the walkthrough directory, yo
 │   ├── 05-checkpoint.md
 ```
 
-* Configuration explains how a repository can be organized into units of content.
-* Publishing shows you how to make your materials available for use in a cohort.
-* Explore rendering options in Markdown Examples.
-* See how Learn enables inline checks for understanding with Challenges.
-* Each unit can assess a student's understanding with a Checkpoint.
+* The 'Configuration' file explains how a repository can be organized into units of content.
+* 'Publishing' shows you how to make your materials available for use in a cohort.
+* Explore rendering options in 'Markdown Examples'.
+* See how Learn enables inline checks for understanding with 'Challenge Examples'.
+* Each unit can assess a student's understanding with 'Checkpoint Example'.
 
 ## Generating Content
 
-The `learn` CLI tool can generate boilerplate markdown for challenges and other custom markdown content (like the callout above) with the command `learn md`. Try it now and see what is available.
+The `learn` CLI tool can generate boilerplate markdown for challenges and other custom markdown content (like the callout above) with the command 
+```
+learn md
+```
+
+so for example, you can see how a callout markdown can be rendered in a content file with
+
+```
+learn md co -o
+```
+
+Try it now and compare it to the content of the `00-hello-world.md` file in your editor. The callout markdown you generated appears much like the callout at the top of the file.
 
 If you use the `-o` flag the content is sent to `STDOUT`, while the `-m` flag produces a minimal version of the content.
 

app/cmd/embeds/walkthrough/01-example-unit/01-configuration.md

@@ -31,7 +31,7 @@ You'll notice the title is not configured in the front matter- it is always deri
 
 ## Tracking configuration in a file
 
-After you ran `learn preview .` you'll see a new file in the root of the walkthrough directory named `autoconfig.yaml`. The yaml frontmatter at the top of each file sets the values for the `autoconfig.yaml` content files.
+After you ran `learn preview .` you'll see a new file in the root of the walkthrough directory named `autoconfig.yaml`. The yaml frontmatter at the top of each file sets the values for the `ContentFiles` key in the `autoconfig.yaml`.
 
 You can see the format and more information for configuration options by running
 ```
@@ -69,7 +69,14 @@ Each unit directory like `01-example-unit/` should have one `description.yaml` f
 
 ## Adding more Units
 
-Create a new Unit directory as a sibling to `01-example-unit/` and name it `02-my-unit/`. Populate it with a single markdown file called `01-playground.md` and write the following contents to the file:
+Create a new Unit directory as a sibling to `01-example-unit/` and name it `02-my-unit/`. Populate it with a single markdown file called `00-playground.md`. From the root of the walkthrough
+
+```
+mkdir 02-my-unit/
+touch 02-my-unit/00-playground.md
+```
+
+Write the following contents to your new file:
 
 ```
 ---
@@ -85,3 +92,4 @@ Then run `learn preview .` again from the root of the walkthrough directory. Fol
 
 We never wrote a `description.yaml` file for our second unit! What did it display for the unit Title and Description? Try adding your own `description.yaml` file inside your `02-my-unit/` directory and change the settings as you see fit. Re-preview to see how Title and Description are now configured.
 
+Try renaming your new unit directory to `00-my-unit/` and preview again with `learn preview .` to see that the ordering 

app/cmd/embeds/walkthrough/01-example-unit/02-publishing.md

@@ -13,13 +13,13 @@ Publishing 'deploys' a new release of curriculum content for that block at that
 
 ## Requirements
 
-In order to publish curriculum, the project must be in a remote git based VCS, and Learn must have permission to access the repository.
+In order to publish curriculum, the project must be in a remote git based version control system, and Learn must have permission to access the repository.
 
 Learn works with GitHub, Gitlab SaaS, and self hosted GitLab instances. Private repositories can be used; when doing so for GitHub, the `github-forge-production` user must have read access to the repository. For GitLab, the `galvanize-learn-production` user must have read access to the project.
 
 ## Push to the Remote
 
-In the VCS of your choice, create a repository/project ([GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github), [GitLab](https://docs.gitlab.com/ee/user/project/)), then commit all contents of the walkthrough:
+In the version control system of your choice, create a repository/project ([GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github), [GitLab](https://docs.gitlab.com/ee/user/project/)), then commit all contents of the walkthrough:
 ```
 git add -A
 git commit -m "testing learn publish"

app/cmd/embeds/walkthrough/01-example-unit/03-markdown-examples.md

@@ -13,6 +13,58 @@ File headers can be written to define attributes for the content file itself, wh
 
 You can use a bare minimum template with the `-m` flag.
 
+## Link to other content in Learn
+
+Links to other markdown files in the repository will navigate within Learn. Write them with a relative path in the repo. For example:
+
+[This is a link to the Challenge Examples file in this repository `04-challenges.md`.](04-challenges.md)
+
+Links to lessons in other repos are possible by using permalinks. Once a block of curriculum is [published](02-publishing.md) and available on a cohort, each content file will have a chain link icon at the top available to instructors and administrators.
+
+Clicking this link will reveal the option to 'Copy page permalink' to your clipboard. Here is an example permalink you can copy:
+
+```
+https://learn-2.galvanize.com/content_link/github.com/gSchool/learn-content/other-challenge-attributes.md
+```
+
+## Link (external)
+
+Links to external content should be absolute links, starting with `http://` or `https://`
+
+[Google](https://www.google.com/)
+
+[Curriculum on github/gSchool](https://github.com/gSchool)
+
+*The markdown examples here are not necessary to read to continue the walkthrough. Read them for reference and to see what's possible with Learn markdown.
+
+## Callouts
+
+Callouts are Learn rendered sections of content to highlight 
+
+### !callout-info
+This information is the most important thing to read on the page!
+### !end-callout
+
+### !callout-warning
+Warnings don't really mean much when you know Danger is still an option.
+### !end-callout
+
+### !callout-danger
+You should probably do what this says.
+### !end-callout
+
+### !callout-success
+Yay?
+### !end-callout
+
+### !callout-secondary
+When grayscale is your style.
+### !end-callout
+
+### !callout-star
+Purple for when you want things to pop!
+### !end-callout
+
 # H1 Top-Level Heading
 
 Galvanize is committed to creating opportunities for Veterans to gain the skills and knowledge they need to enter the tech industry after service to their country. As Veterans Day approaches, we’ll be chronicling the stories…
@@ -61,20 +113,6 @@ Bulleted with `-`
 - two
 - three
 
-## Link to other content in Learn
-
-Links to markdown files in the curriculum will redirect within Learn. Write them with a relative path in the repo. Links to lessons in other repos are not supported.
-
-[challenge examples](04-challenges.md)
-
-## Link (external)
-
-Links to external content should be absolute links, starting with `http://` or `https://`
-
-[Google](https://www.google.com/)
-
-[Curriculum on github/gSchool](https://github.com/gSchool)
-
 ## Images
 
 Images included in your repo will be automatically uploaded to S3 for display on Learn.
@@ -119,32 +157,6 @@ Here is a table with a header row
 > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone.
 
 
-## Callouts
-
-### !callout-info
-This information is the most important thing to read on the page!
-### !end-callout
-
-### !callout-warning
-Warnings don't really mean much when you know Danger is still an option.
-### !end-callout
-
-### !callout-danger
-You should probably do what this says.
-### !end-callout
-
-### !callout-success
-Yay?
-### !end-callout
-
-### !callout-secondary
-When grayscale is your style.
-### !end-callout
-
-### !callout-star
-Purple for when you want things to pop!
-### !end-callout
-
 ## Rendering LaTeX for Math equations
 
 Block-style LaTeX supported.

app/cmd/embeds/walkthrough/01-example-unit/04-challenges.md

@@ -11,6 +11,19 @@ You can view a complete list of available challenge types by running `learn md`
 
 You can use a bare minimum template with the `-m` flag.
 
+## Structure
+
+You can see the basic structure of a multiple choice question by running:
+```
+learn md mc -om
+```
+
+Each challenge begins with a `### !challenge` delimiter, and ends with `### !end-challenge` delimiter. Short one-line challenge attributes are defined in the challenge header, such as the `type`, `id`, `title`, or some type specific attributes such as `language` for code snippets.
+
+Other attributes are multiline, and are given their own delimiters. For example the `multiple-choice` type challenge requires a section to configure the available options; the delimiter for that section is `##### !options` and `##### !end-options`.
+
+When generating challenges with the `learn md` command, you can see explanations in comments for challenge attributes specific to that challenge. If you wish to omit these comments for a minimal template, pass the `-m` flag when generating the challenge.
+
 ## Examples of Types
 
 * multiple choice (select one)
@@ -22,6 +35,7 @@ You can use a bare minimum template with the `-m` flag.
 * custom-snippet--write your own `Dockerfile` and `test.sh` to allow student code to run in a customized container
 * project, testable project (code locally, submit a repo)
 
+*Don't feel the need to correctly answer all the challenges below to complete the walkthrough, they are here for reference and to see how they render in Learn.*
 
 ## Multiple Choice
 

app/cmd/guide.go

@@ -96,10 +96,10 @@ var guideCmd = &cobra.Command{
 
 		fmt.Println(`
 Success!
-========
-
-Open kj`)
+========`)
 		fmt.Printf("\nTo get started run 'cd %s && learn preview 01-example-unit/00-hello-world.md' and follow the instructions to find your content.\n\n", guideDir)
+
+		fmt.Println(`Open the learn-curriculum-walkthrough directory in your favorite editor while working through the preview.`)
 	},
 }