doc(subplot.md): add section to explain given/when/then

We may want to copy or move this to a separate, more user-oriented
document later, but this is the one place we currently have for
Subplot documentation.

1 files changed, 45 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index 3a7d9d7..d701995 100644
--- a/subplot.md
+++ b/subplot.md
@@ -307,6 +307,51 @@ understood by Subplot. We will not specify Pandoc's dialect of
 Markdown here, only the parts Subplot pays attention to.
 
 
+## Scenario language
+
+The scenarios are core to Subplot. They express what the detailed
+acceptance criteria are and how they're verified. The scenarios are
+meant to be understood by both all human stakeholders and the Subplot
+software. As such, they are expressed in a somewhat stilted language
+that resembles English, but is just formal enough that it can also be
+understood by a computer.
+
+A scenario is a sequence of steps. A step can be setup to prepare for
+an action, an action, or an examination of the effect an action had.
+For example, a scenario to verify that a backup system works might
+look like the following:
+
+~~~~~~{.markdown .numberLines}
+~~~scenario
+given a backup server
+when I make a backup
+and I restore the backup
+then the restored data is identical to the original data
+~~~
+~~~~~~
+
+This is not magic. The three kinds of steps are each identified by the
+first word in the step.
+
+* `given` means it's a step to set up the environment for the scenario
+* `when` means it's a step with the action that the scenario verifies
+* `then` means it's a step to examine the results of the action
+
+The `and` keyword is special in that it means the step is the same
+kind as the previous step. In the example, on line 4, it means the
+step is a `when` step.
+
+Each step is implemented by a bit of code, provided by the author of
+the subplot document. The step is _bound_ to the code via a binding
+file, via the text of the step: if the text is like this, then call
+that function. Bindings files are described in detail shortly below.
+
+The three kinds of steps exist to make scenarios easier to understand
+by humans. Subplot itself does not actually care if a step is setup,
+action, or examination, but it's easier for humans reading the
+scenario, or writing the corresponding code, if each step only does
+the kind of work that is implied by the kind of step it's bound to.
+
 ## Document markup
 
 [Pandoc]: https://pandoc.org/