Merge branch 'acceptance-what' into 'main'

docs: explain concepts, suggest a workflow

Closes #211

See merge request subplot/subplot!195

1 files changed, 44 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index 07c07de..29a1587 100644
--- a/subplot.md
+++ b/subplot.md
@@ -16,6 +16,50 @@ document.
 
 [Cucumber]: https://en.wikipedia.org/wiki/Cucumber_(software)
 
+## Acceptance criteria and acceptance tests
+
+We define the various concepts relevant to Subplot as follows:
+
+* **Acceptance criteria**: What the stakeholders require of the system
+  for them to be happy with it and use it.
+
+* **Stakeholder**: Someone with a keen interest in the success of a
+  system. They might be a paying client, someone who uses the system,
+  or someone involved in developing the system. Depending on the
+  system and project, some stakeholders may have a bigger say than
+  others.
+
+* **Acceptance test**: How stakeholders verify that the system
+  fulfills the acceptance criteria, in an automated way. Some criteria
+  may not be possible to verify automatically.
+
+* **Scenario**: In Subplot, the acceptance criteria are written as
+  freeform prose, with diagrams, etc. The scenarios, which are
+  embedded blocks of Subplot scenario language, capture the mechanisms
+  of verifying that criteria are met - the acceptance tests - showing
+  step by step how to determine that the software system is acceptable
+  to the stakeholders.
+
+## A basic workflow for using Subplot
+
+We recommend the following initial approach to using Subplot, which
+you can vary based on your particular needs and circumstances.
+
+1. Start with a small acceptance document that you think expresses
+   some useful requirements.
+2. Write some acceptance criteria and have them agreed among the
+   stakeholders.
+3. Write scenarios to verify that the criteria are met, and have those
+   scenarios agreed by the stakeholders.
+4. Write bindings and test functions, so that as the code is written
+   it can be tested against the acceptance criteria. 
+5. Iterate on this in short cycles to maximise discussion and
+   stakeholder buy-in.
+
+You definitely want to keep the subplot document source code in
+version control. You certainly need to have people who can write
+technical text that's aimed at all your stakeholders.
+
 ## Subplot architecture
 
 Subplot reads an input document, in Markdown, and generates a typeset