Added missing sections in the Introduction

    Who is `yarn` for?
    What kinds of testing is `yarn` for?
    Why `yarn` instead of other tools?
    Why not cmdtest?

1 files changed, 73 insertions, 12 deletions

diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn
index d63dee0..df2fa63 100644
--- a/yarn-doc/index.mdwn
+++ b/yarn-doc/index.mdwn
@@ -8,8 +8,8 @@ is currently not yet written.
 
 Mission
 -------
-This manual will provide all the information needed by Yarn users to enable
-them to use Yarn effectively in their development projects.
+This manual will provide all the information needed by `yarn` users to enable
+them to use `yarn` effectively in their development projects.
 
 The information will be
 
@@ -30,20 +30,22 @@ Document Status
 * Outline
 * Mission
 * this Document Status section
-
-### What's New
-
 * Writing Scenarios
     * Test Language Specification
 * Introduction
     * Skeleton
     * What is `yarn`?
 
+### What's New
+* Introduction
+    * Who is `yarn` for?
+    * What kinds of testing is `yarn` for?
+    * Why `yarn` instead of other tools?
+    * Why not cmdtest?
+
 
 ### What's Next
 
-* Introduction
-    * Remaining sections
 * `yarn`'s command line
 *  How to embed `yarn` in Markdown
 
@@ -70,21 +72,81 @@ a backup program works, at least for one simple case.
     AND an empty backup repository
     WHEN a backup is made
     THEN the data can be restored
-
-(Note the addition of AND: you can have multiple GIVEN, WHEN, and
+ (Note the addition of AND: you can have multiple GIVEN, WHEN, and
 THEN statements. The AND keyword makes the text be more readable.)
 
 
 ### Who is `yarn` for?
 
-### Who are the test suites written in `yarn` for?
-
+Anyone involved in the testing process, from those closest to the process
+(the programmers and the engineers implementing the tests) to those
+furthest away (architects, customers or their representatives in the
+project).
+
+* Architects: specify the tests by writing scenarios based on requirements,
+and the narrative text that goes with them;
+* Customers: gain understanding of what they will be getting, of what the
+software will do;
+* Programmers: create and run tests to verify and debug their code;
+* Test engineers: understand what tests they need to implement and
+run;
+* Project Managers:
+    * monitor progress of testing activities (tests implemented / run);
+    * understand current levels of quality (tests passed / failed).
+
+(In small developments, these roles are often filled by the same person, or
+by a very small group of people. In larger development projects, the roles
+may be filled by people in different teams, which may be dispersed both
+geographically and administratively.)
+ 
 ### What kinds of testing is `yarn` for?
 
+`yarn` can be used for testing anything that can be driven using the
+command line or shell scripts: in practice that means 'anything at all'.
+Anything from small, single-engineer developments (add some examples?)
+through to very large, multi-team, enterprise-level developments (add some
+examples?).
+ 
+Testing GUIs can be challenging, but there are tools for the purpose, and
+these tools can often be driven from scripts - both for doing things in the
+GUI and for checking the outcomes. In these cases, you wouldn't use `yarn`
+for implementing the test, but there's no reason not to use it for driving
+the tests and reporting the outcomes.
+
+Because `yarn` is scriptable, it works well as part of a Continuous
+Integration process, using tools such as Jenkins.
+
 ### Why `yarn` instead of other tools?
 
+`yarn`'s main strength is that scenarios are written in human readable
+language, allowing them to be read, understood and validated by people who
+are far removed from the testing process. You don't need to be able to
+write (or understand) `IMPLEMENTS` statements to understand a `yarn`.
+
 ### Why not cmdtest?
 
+A single test in `cmdtest` may involve up to eight separate files (the
+inputs, outputs, exit code, setup and teardown scripts specific to the
+tests, plus the setup and teardown scripts common to all tests). Also,
+unless the test author has included narrative comments, it can difficult to
+understand the purpose and struture of the test - exactly what is it
+testing, and how. These details must be inferred from the implementation of
+the test (which is split between the different files). This in turn makes
+the tests less accessible to anyone but their creator, and even they may
+have problems interpreting the test when returning to it later in the
+project lifecycle.
+
+With `yarn`, the tests are 'self-documenting' - the purpose and structure
+of the tests are
+
+* made explicit in each scenario's narrative text and its steps;
+* documented in natural language;
+* separated from the implementation.
+
+So while `cmdtest` could be described as a testing tool for programmers,
+`yarn` is intended as a tool for *all* the stakeholders in the testing
+process. 
+
 Writing Scenarios
 -----------------
 
@@ -232,7 +294,6 @@ Semantics:
   are not run.
 
 
-
 Outline
 -------