improved docs

Author: ShMcK

_includes/docs/docs.html

@@ -13,7 +13,7 @@ <h1 id="overview" class="page-header">Overview</h1>
             CodeRoad aims to make building & sharing interactive tutorials as easy as possible.
           </blockquote>
 
-          <div class="lead">We hope to create fun and maintainable coding tutorials that actually improve with time. We hope to create a world where students become teachers, teachers become empowered & coders become better, faster. But first, we need to get some tutorials built.</div>
+          <div class="lead">We hope to create fun and maintainable coding tutorials that actually improve with time. We hope to see students become teachers, teachers become empowered, and coders become better, faster. But first, let's get some interactive tutorials built. That's where you come in.</div>
 
           <a href="/build" class="btn btn-default btn-lg"><i class="fa fa-road fa-fw"></i> <span class="network-name">Read an Overview of Building a Tutorial</span></a>
 

_posts/2016-01-01-installation.md

@@ -5,7 +5,9 @@ id: install
 file: 2016-01-01-installation.md
 ---
 
-To build a tutorial with CodeRoad, you'll need to install both **Atom-CodeRoad** & the **CodeRoad-CLI**.
+To play a tutorial, you'll only need **Atom-CodeRoad**.
+
+But to build a tutorial, you'll also need the **CodeRoad-CLI**.
 
 ### Atom CodeRoad
 

_posts/2016-01-02-development.md

@@ -7,7 +7,7 @@ file: 2016-01-02-development.md
 
 ### Create
 
-To get setup quickly with CodeRoad, either clone a tutorial repo or use the CLI.
+Get setup quickly with CodeRoad: either [clone a tutorial repo](https://git-scm.com/docs/git-clone) or use the *CodeRoad-CLI*.
 
 In your development directory, run **create** with your new package name.
 

_posts/2016-01-07-test-examples.md

@@ -7,43 +7,43 @@ file: 2016-01-07-test-examples.md
 
 Here are examples using *mocha* with *chai*'s *expect*. See the [docs](http://chaijs.com/api/bdd/).
 
-##### exists
+#### exists
 
     it('doesn\'t exist', function() {
       expect(target).to.not.be.undefined;
     });
 
-##### type
+#### type
 
     it('should be a function', function() {
       expect(target).to.be.a('function');
     });
 
-##### function params
+#### function params
 
     it('should have two parameters', function() {
       expect(target).to.have.length(2);
     });
 
-##### function returns
+#### function returns
 
     it('should add one to the number', function () {
       expect(addOne(1)).to.equal(2);
     });
 
-##### equals
+#### equals
 
     it('should be 42', function () {
       expect(target).to.equal(42);
     });
 
-##### deep equals (with objects or arrays)
+#### deep equals (with objects or arrays)
 
     it('should be {a: 42}', function () {
       expect(target).to.deep.equal({a: 42});
     });
 
-##### regex
+#### regex
 
     it('should access the property "prop"', function () {
       var regex1 = /\.prop/;            // dot notation
@@ -53,7 +53,7 @@ Here are examples using *mocha* with *chai*'s *expect*. See the [docs](http://ch
       expect(result).to.be.true;
     });
 
-##### spies
+#### spies
 
 You can use [*sinon*](http://sinonjs.org/docs/) or [*chai-spies*](https://github.com/chaijs/chai-spies) to create a spy. See an example below:
 

_posts/2016-01-08-config.md

@@ -4,4 +4,29 @@ title: Config
 id: config
 file: 2016-01-08-config.md
 ---
-coming soon
+CodeRoad tutorial configurations can be set in the *package.json* config.
+
+    "config": {
+      "testDir": "tutorial",
+      "testSuffix": ".spec.js",
+      "testRunner": "mocha-coderoad",
+      "edit": true
+    }
+
+This section will likely expand in the future. For now, let's go over some of these.
+
+#### testDir
+
+The relative path to the unit test directory. This makes writing unit tests paths easier.
+
+#### testSuffix
+
+The common suffix for unit tests. Also making writing unit test paths shorter.
+
+#### testRunner
+
+Specified test runner. Currently only "mocha-coderoad" is available.
+
+#### edit
+
+If set to true, *Atom-CodeRoad* will allow users to submit issues or submit markdown pull requests. You will also need to specify "repository" & "bugs" in your *package.json* file. See an [example config file](https://github.com/coderoad/coderoad-functional-school/blob/master/package.json).

_posts/2016-01-10-testRunner.md

@@ -4,8 +4,78 @@ title: Test Runners
 id: test-runner
 file: 2016-01-10-testRunner.md
 ---
-coming soon
+A test runner works by creating a child process and calling a test framework with target files.
 
-### Mocha-CodeRoad
+In this way, the test runner not only determines how unit tests will be written, but it actually determines the programming language used in the tutorial.
+
+> Any programming language could be used with CodeRoad, you need only change the test runner.
+
+### Current Test Runners
+
+* Javascript: [*mocha-coderoad*](https://github.com/coderoad/mocha-coderoad)
 
 ### How to Build a Test Runner
+
+If you're interested in helping CodeRoad support a programming language of your choice, here's how to set up the test runner.
+
+The test runner should spawn a child process. Think of this like your program opening up a terminal, typing in command line commands, then collecting and returning the the results to *Atom-CodeRoad*. See [an example child process created in *mocha-coderoad*](https://github.com/coderoad/mocha-coderoad/blob/master/src/create-runner.js).
+
+The test runner is called with four ordered inputs, two of which act as callback functions that return the log & result to *Atom-CodeRoad*.
+
+See a brief example from the [*mocha-coderoad* runner](https://github.com/coderoad/mocha-coderoad/blob/master/src/runner.js).
+
+
+    export default function runner(testFile, config, handleResult, handleLog) {
+      ...
+      handleLog(msg); // returns log
+      ...
+      handleResult(result); // returns test result
+    }
+
+Let's look at these four inputs in more detail.
+
+#### 1. testFile
+
+The absolute path to a file containing all concatenated page tests. Call your test framework with this.
+
+#### 2. config
+
+A JSON object of configurations, see an example below
+
+
+    {
+      "dir": "path/to/user/project",
+      "tutorial": "coderoad-package-name",
+      "tutorialDir": "/path/to/installed/tutorial/",
+      "taskPosition": 0
+    }
+
+
+#### 3. handleResult
+
+A callback function that should be called with the **result** object. Results should either pass if all pass, or fail if any test fails.
+
+##### pass
+
+    {
+      "pass": true,
+      "taskPosition": 1,
+      "change": 1,
+      "msg": "Task 1 Complete"
+    }
+
+The result should output the 'taskPosition' after the test. 'change' represents the difference between the starting 'taskPosition' and the resulting 'taskPosition'.
+
+##### fail
+
+    {
+      "pass": false,
+      "taskPosition": 0,
+      "change": 0,
+      "msg": "`var secret` should be 42",
+      "timedOut": false
+    }
+
+#### 4. handleLog
+
+A callback function that should be called with a string **log** statement