1 files changed, 57 insertions, 0 deletions
diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn
new file mode 100644
index 0000000..7deaffb
--- /dev/null
+++ b/yarn-doc/index.mdwn
@@ -0,0 +1,57 @@
+% Yarn manual
+
+Yarn
+====
+
+FIXME: This will become a manual for writing test suites in yarn. It
+is currently not yet written.
+
+Outline
+-------
+
+* Introduction
+  - what is yarn?
+  - who is yarn for?
+  - who are the test suites written in yarn for?
+  - what kinds of testing is yarn for?
+  - why yarn instead of other tools?
+    - why not cmdtest?
+  - NOT installation instructions
+* Examples
+  - a test suite for "hello world"
+    - make the files available so people can try things for themselves
+  - a few simple scenarios
+* The yarn testing language
+  - Markdown with blockquotes for the executable code
+  - SCENARIO + the step-wise keywords
+  - IMPLEMENTS sections
+* Running yarn
+  - command line syntax
+  - examples of various ways to run yarn in different scenarios:
+    - how to run just one scenario
+    - how to run yarn under cron or jenkins
+  - formatting a test suite in yarn with pandoc
+* Best practices
+  - this chapter will describe best practices for writing test suites
+    with yarn
+  - how to structure the files: what to put in each *.yarn file, e.g.,
+    where should IMPLEMENTS go
+  - how to write test suites that make it easy to debug things when a
+    test case fails
+  - good phrasing guidelines for yarn scenario names and step names
+  - what things are good to keep visible to the reader, what are
+    better hidden inside impementations of steps, with examples from
+    real projects using yarn
+  - guidelines for well-defined steps that are easy to understand and
+    easy to implement
+  - anti-patterns: things that are good to avoid
+  - make tests fast
+  - make test code be obviously correct; make test code be the best
+    code
+  - when is it OK to skip scenarios?
+* Case studies
+  - this chapter will discuss ways to use yarn in things that are not
+    just "run this program and examine the output"
+  - start a daemon in the background, kill it at the end of a scenario
+  - how to use a really heavy-weight thing in test suites (e.g., start
+    a database server for all scenarios to share)