update docs

Signed-off-by: shmck <shawn.j.mckay@gmail.com>
coderoad · ShMcK · Aug 16, 2020 · Aug 16, 2020 · Aug 16, 2020 · Aug 16, 2020
commit c3ceab2e9a2abe0b3b973246a6a95d0f1382d175
diff --git a/docs/docs/build-tutorial.md b/docs/docs/build-tutorial.md
@@ -4,12 +4,157 @@ title: Building a Tutorial
 sidebar_label: Building a Tutorial
 ---
 
-A tutorial is made from a GitHub repository that includes three parts:
+## Requirements
 
-1. Markdown
-2. YAML
-3. Git Commits
+To create a tutorial in CodeRoad, there are a few requirements.
 
-The Markdown and YAML live on the master branch of the repo, and the Git commits live on a version branch.
+1. An understanding of how to write software tests in your target language (JavaScript, Python, etc).
+2. A familiarity with Git.
 
-We'll go into each parts in more detail.
+## Disclaimer
+
+Before we start, note that if any of these processes are workarounds to accomplish two necessary goals:
+
+1. an intermediary working product without a full featured build tool.
+2. zero server costs so that CodeRoad can scale and remain free.
+
+If this project becomes popular, I'll develop an all encompassing build tool.
+
+If you're interesting in creating a tutorial, reach out at `coderoadapp@gmail.com` and I'll be happy to help!
+
+## Tutorial Elements
+
+At its core, a CodeRoad tutorial is a JSON file. See an [example tutorial.json file](https://raw.githubusercontent.com/coderoad/fcc-learn-npm/master/tutorial.json).
+
+The tutorial JSON file is produced out of several resources:
+
+1. Text (Markdown)
+2. Config (YAML)
+3. Git Commits on specific branches
+
+CodeRoad uses a [build CLI](https://github.com/coderoad/coderoad-cli) to validate and combine the three core parts.
+
+Let's go through each briefly.
+
+### 1. Text
+
+Markdown is used for formatting, editing and visualizing text the user will see in CodeRoad. If you're unfamiliar with Markdown, checkout [the mastering markdown guide](https://guides.github.com/features/mastering-markdown/).
+
+See an example `TUTORIAL.md` file:
+
+```md
+# Tutorial Title
+
+> Tutorial summary introduction
+
+## 1. Title of Lesson 1
+
+> Lesson 1 summary
+
+Lesson 1 decription and content.
+
+### 1.1
+
+A description of what to do for the first task
+
+#### HINTS
+
+- This is a hint for task 1.1
+- This is another hint for task 1.1
+```
+
+The markdown will be parsed by the build tool to transform this text into the tutorial.json. Note that there is a specific format for the content that you can probably understand from the content.
+
+Note that:
+
+1. Lessons need to start with `## $X.` where `$X` is the lesson number. The text afterwards will display as the lesson title.
+2. Tasks need to start with `### $X.$Y`, where `$X` is the lesson number and `$Y` is the task number.
+
+These complications are to make it easy for the build tool to match up levels and tasks.
+
+### 2. Config
+
+To keep configurations clean, the config lives in a `coderoad.yaml` file. If you're unfamiliar with yaml, checkout [a beginners guide to YAML](https://circleci.com/blog/what-is-yaml-a-beginner-s-guide).
+
+The config file describes hooks/actions to run when a lesson starts, a level starts or a task starts.
+
+Add the following to your `coderoad.yaml` file.
+
+```yaml
+version: '0.1.0'
+config:
+  testRunner:
+    command: ./node_modules/.bin/mocha
+    args:
+      filter: --grep
+      tap: --reporter=mocha-tap-reporter
+    directory: .coderoad
+  repo:
+    uri: https://github.com/username/repo
+    branch: v0.1.0
+  dependencies:
+    - name: node
+      version: '>=10'
+  setup:
+    commands:
+      - cd .coderoad && npm install
+levels:
+  - id: '1'
+    steps:
+      - id: '1.1'
+```
+
+We'll look more into config later, but for now just understand that its setting up a particular test runner (Mocha.js) in the `.coderoad` directory of the project. The code will run a specified repo and branch, and the environment it runs on should at least have Node version 10 or later.
+
+Also note that the level & step IDs need to match up with the IDs in the `TUTORIAL.md` file.
+
+### 3. Branches
+
+CodeRoad uses GitHub like a server. Configuration code is kept on the master branch, and code is kept on versioned branches.
+
+```text
+~master
+    - TUTORIAL.md
+    - coderoad.yaml
+    - tutorial.json
+    - .gitignore
+~v0.1.0
+    ...code
+~v0.2.0
+    ...code
+```
+
+We keep versions on branches to avoid breaking changes. A user who started a tutorial earlier may still be continuing earlier progress.
+
+### 4. Code
+
+The first commit for a tutorial should setup the test runner, otherwise nothing will work.
+
+CodeRoad has certain rules for commit names. These names are used by the build script for pulling in commit hashes for the tutorial.json.
+
+See [an example code branch](https://github.com/coderoad/fcc-learn-npm/commits/v0.4.1), and note how each commit name is formatted in a specific way.
+
+1. INIT
+   - basic project setup code
+   - add test runner dependencies
+   - .vscode workspace configurations
+2. 1.1
+   - add tests
+   - add testing dependencies
+   - add scaffolding code (if needed)
+3. 1.1S
+   - the code required to make the tests pass
+
+If you run into an issue and need to rename a commit, read [how to change a commit message](https://docs.github.com/en/github/committing-changes-to-your-project/changing-a-commit-message).
+
+What makes CodeRoad work is the tests and solutions.
+
+### 5. Build CLI
+
+When a tutorial is ready for testing, you can run the [coderoad-cli](https://github.com/coderoad/coderoad-cli) to put everything together.
+
+Run `coderoad build` to produce the `tutorial.json` file, then load that file into your CodeRoad extension. There is an option to load from files on the select tutorial page.
+
+### Conclusion
+
+For more, see [create a practice tutorial](/docs/create-a-practice-tutorial)
diff --git a/docs/docs/yaml.md → docs/docs/config-docs.md b/docs/docs/yaml.md → docs/docs/config-docs.md
@@ -1,7 +1,7 @@
 ---
-id: yaml
-title: Yaml
-sidebar_label: Yaml
+id: config-docs
+title: Config
+sidebar_label: Config
 ---
 
 ### Description

diff --git a/docs/docs/config-yml.md b/docs/docs/config-yml.md
diff --git a/docs/docs/create-a-practice-tutorial.md b/docs/docs/create-a-practice-tutorial.md
@@ -177,10 +177,10 @@ config:
     command: ./node_modules/.bin/mocha
     args:
       tap: --reporter=mocha-tap-reporter
-    setup:
-      commands:
-        - npm install
     directory: coderoad
+  setup:
+    commands:
+      - cd coderoad && npm install
   repo:
     uri: https://github.com/moT01/first-tut
     branch: v0.1.0

diff --git a/docs/docs/errors.md b/docs/docs/errors.md
diff --git a/docs/docs/git-timeline.md b/docs/docs/git-timeline.md
diff --git a/docs/docs/hooks-actions.md b/docs/docs/hooks-actions.md
@@ -0,0 +1,24 @@
+---
+id: hooks-actions
+title: Hooks & Actions
+sidebar_label: Hooks & Actions
+---
+
+To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
+
+An action is a piece of functionality that can be run. These include:
+
+- `commands` - a list of cli commands to run. For example, "npm install"
+- `vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
+- `watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
+- `files` - a list of files to open in the users workspace to drive the users attention.
+- `subtasks` - a task made up of multiple other tests where all must pass to continue
+- `filter` - a regex passed into the test runner to limit the tests returned
+
+A hook in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
+
+- `config.setup` - when the tutorial setup. This is a great place to setup your test runner.
+- `task.setup` - when a task is started
+- `task.solution` - when a solution is loaded from a reset
+
+Hooks and actions combine to provide a flexible environment for tutorial development.
diff --git a/docs/docs/how-coderoad-works.md b/docs/docs/how-coderoad-works.md
@@ -8,7 +8,7 @@ There are really a few major pieces to understand how CodeRoad works.
 
 1. [How Tests Work](#how-tests-work)
 
-2. [How CodeRoad is Built on Git](#built-on-git)
+2. [What it means to say CodeRoad is "Built on Git"](#built-on-git)
 
 3. [How CodeRoad Hooks & Actions work](#how-hooks-and-actions-work)
 
@@ -70,19 +70,12 @@ In the example above you can see the user is “reset” back to the original tu
 
 To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
 
-An **action** is a piece of functionality that can be run. These include:
-
-- `commands` - a list of cli commands to run. For example, "npm install"
-- `vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
-- `watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
-- `files` - a list of files to open in the users workspace to drive the users attention.
-- `subtasks` - a task made up of multiple other tests where all must pass to continue
-- `filter` - a regex passed into the test runner to limit the tests returned
+An **action** is a piece of functionality that can be run, such a CLI command, or tapping into the VSCode API.
 
 A **hook** in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
 
-- `config.setup` - when the tutorial setup. This is a great place to setup your test runner.
-- `task.setup` - when a task is started
-- `task.solution` - when a solution is loaded from a [reset](#reset)
+- when the tutorial starts. This is a great place to setup your test runner.
+- when a task is started
+- when a solution is loaded from a [reset](#reset)
 
-Hooks and actions combined provide a flexible environment for tutorial development.
+Hooks and actions combine to provide a flexible environment for tutorial development.