diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-07-31 20:23:47 +0300 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-07-31 20:25:18 +0300 |
commit | aa072685158cd38fc57a4d9c41188ff643b04af3 (patch) | |
tree | ab796d7a8c7bf9688b51b0268ee60bcd6e102250 | |
parent | 31170280362e6a9827aee0090ef19b875245f0df (diff) | |
download | subplot-aa072685158cd38fc57a4d9c41188ff643b04af3.tar.gz |
docs: explain concepts, suggest a workflow
Sponsored-by: author
-rw-r--r-- | subplot.md | 44 |
1 files changed, 44 insertions, 0 deletions
@@ -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 |