From aa072685158cd38fc57a4d9c41188ff643b04af3 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 31 Jul 2021 20:23:47 +0300 Subject: docs: explain concepts, suggest a workflow Sponsored-by: author --- subplot.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) 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 -- cgit v1.2.1