subplot.md: Document scenario language a bit more

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>

1 files changed, 76 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index ef63b30..f87856d 100644
--- a/subplot.md
+++ b/subplot.md
@@ -400,6 +400,82 @@ 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.
 
+### Using Subplot's language effectively.
+
+Your subplot scenarios will be best understood when they use the subplot
+language in a fashion consistent with all subplot scenarios in your project(s).
+As with programming languages, it's possible to place your own style on your
+subplots, indeed there is no inherent internal implementation difference between
+how `given`, `when` and `then` steps are processed (other than that `given`
+steps often also have cleanup functions associated with them).
+
+There is, however, value in having consistency between
+the subplot scenarios in *different* projects.  Here is how we recommend you use
+the Subplot language, and indeed how we use it in Subplot and related projects…
+
+When you are formulating your scenarios, it is common to try and use phraseology
+along the lines of _if this happens then that is the case_ but this is not
+language which works well with subplot.  Scenarios describe what will happen in
+the success case.  As such we don't construct scenarios which say _if foo happens
+then the case fails_ instead we say _when I do the thing then foo does not happen_.
+This is a subtle but critical shift in the construction of your test cases which
+will mean that they map more effectively to scenarios.
+
+Scenarios work best when they describe how some entity (human or otherwise)
+actually goes about successfully achieving their goal.  They start out by setting
+the scene for the goal (`given`) they go on to describe the actions/activity
+undertaken in order for the goal to be achieved (`when`) and they describe how
+the entity knows that the goal has been achieved (`then`).  By writing in this
+active goal-oriented fashion, your scenarios will flow better and be easier for
+all stakeholders to understand.
+
+In general you should use `given` statements where you do not wish to go into
+the detail of what it means for the statement to have been run, you simply wish
+to inform the reader that some precondition is met.  These statements are often
+best along the lines of `given a setup which works` or `given a development enviroment`
+or somesuch.
+
+The `when` statements should be best used to denote **active** steps. These are
+the steps which your putative actors or personae use to achieve their goals.
+These often work best in the form `when I do the thing` or
+`when the user does the thing`.
+
+The `then` statements are the crux of the scenario, they are the **validation**
+steps.  These are the steps which tell the reader of the scenario how the actor
+knows that their action (the `when` steps) has had the desired outcome.  This
+could be of the form `then some output is present` or `then it exits successfully`.
+
+With all that in mind, a good scenario looks like
+
+```scenario
+given the necessary starting conditions
+when I do the required actions
+then the desired outcome is achieved
+```
+
+Given all that, however, it's worth considering some pitfalls to avoid when
+writing your scenarios.
+
+It's best to avoid overly precise or overly technical details in your scenario
+language (unless that's necessary to properly describe your goal etc.)  So
+it's best to say things like `then the output file is valid JSON` rather than
+`then the output file contains {"foo": "bar", "baz": 7}`.  Obviously if the
+actual values are important then again, statements such as `then the output file
+has a key "foo" which contains the value "bar"` or similar.
+
+Try not to change "person" or voice in your scenarios unless there are multiple
+entities involved in telling your stories. For example, if you have a scenario
+statement of `when I run fooprogram` do not also have statements in the passive
+such as `when fooprogram is run`. It's reasonable to switch between `when` and
+`then` statements (`then the output is good`) but try not to have multiple
+`then` statements which switch it up, such as `then I have an output file`,
+`and the output file is ok`.
+
+If you're likely to copy-paste your scenario statements around, do not use `and`
+as a scenario keyword, even though it's valid to do so.  Instead start all your
+scenario statements with the correct `given`, `when`, or `then`.  The typesetter
+will deal with formatting that nicely for you.
+
 ## Document markup
 
 [Pandoc]: https://pandoc.org/