Update docs to explain purpose of SampleProjects (Arduino-CI#156)

- Update docs to explain purpose of SampleProjects and avoid impression that they are templates to be followed too closely.
- Provide alternative `bundle install` command (the original one doesn't work on macOS 10.16).
- Correct location for your project.

Author: James Foster

README.md

@@ -82,10 +82,10 @@ vendor
 
 ### Installing the Dependencies
 
-Fulfilling the `arduino_ci` library dependency is as easy as running this command:
-
+Fulfilling the `arduino_ci` library dependency is as easy as running either of these two commands:
 ```
-$ bundle install
+$ bundle install   # adds packages to global library (may require admin rights)
+$ bundle install --path vendor/bundle   # adds packages to local library
 ```
 
 

SampleProjects/DoSomething/test/README.md

@@ -1,7 +1,9 @@
-# Purpose
+## Purpose
 
-These files are designed to test the Ruby gem itself, such that its basic tasks of library installation and compilation can be verified.  (i.e., use minimal C++ files -- feature tests for C++ unittest/arduino code belong in `../TestSomething/test/`).
+These files are designed to test the testing framework (the Ruby gem) itself, library installation and compilation. (Feature tests for C++ unittest/arduino code belong in `../TestSomething/test/`.)
 
 ## Naming convention
 
-Files in this directory are expected to have names that either contains "bad" if it is expected to fail or "good" if it is expected to pass.  This provides a signal to `rspec` for how the code is expected to perform.
+Files in this directory are given names that either contains "bad" (if it is expected to fail) or "good" (if it is expected to pass).  This provides a signal to `rspec` for how the code is expected to perform (see `spec/cpp_library_spec.rb`). 
+
+When writing your own tests you should not follow this ("bad" and "good") naming convention. You should write all your tests expecting them to pass (relying on this `DoSomething` test to ensure that failures are actually noticed!).

SampleProjects/README.md

@@ -1,7 +1,7 @@
 Arduino Sample Projects
 =======================
 
-This directory contains example projects that are meant to be built with this gem.
+This directory contains projects that are meant to be built with and tested by this gem. Although this directory is named `SampleProjects`, it is by no means optional. These project test the testing framework itself, but also provide examples of how you might write your own tests (which should be placed in your system's Arduino `libraries` directory). 
 
-* "DoSomething" is a bare implementation of a library with a test.  Test files prefixed with "bad-" are expected to fail; this is checked as part of the testing on arduino_ci itself.
-* "TestSomething" contains a minimial library, but tests for all the mock features of arduino_ci.
+* "DoSomething" is a simple test of the testing framework (arduino_ci) itself to verfy that passes and failures are properly identified and reported.
+* "TestSomething" contains tests for all the mock features of arduino_ci.