From d7b1d5bb7e3c596c6afbb4253a75b18815205151 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 1 Jul 2023 13:37:46 +0300 Subject: docs: flesh out the FAQ Sponsored-by: author --- faq.mdwn | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/faq.mdwn b/faq.mdwn index 7ef6737..20c26d7 100644 --- a/faq.mdwn +++ b/faq.mdwn @@ -1,12 +1,45 @@ [[!meta title="FAQ or Frequently Asked Questions"]] +# What is Subplot? + +Subplot a tool to document acceptance criteria and requirements, and +how they're verified, in a way that all stakeholders can understand +and sign off on. Almost as a side effect, it can generate code to do +the verification automatically. + +The primary goal of Subplot is to make sure the software being built +is the right software, and as a side effect to verify that at least +the most important requirements that can be verified automatically are +met. + +# How does Subplot work? + +Basically, you write a document, which embeds verification scenarios +using a given/when/then type language. + +The document is then processed in one way to produce a human readable, +formatted, typeset version that all stakeholders read and are asked to +agree on. + +Processed another way, the document results in code that executes the +verification scenario. Simplified: each given/when/then step is mapped +to a function call that is given specific parts of the step text as +arguments. + + # How does Subplot differ from Cucumber? [Cucumber]: https://en.wikipedia.org/wiki/Cucumber_(software) [Gherkin]: https://en.wikipedia.org/wiki/Cucumber_(software)#Gherkin_language -[Cucumber][] is a tool for running test suites written in [Gherkin][], -whereas Subplot is a tool for typesetting technical documentation -which happens to, as a side effect, output test suites based on a -Gherkin-like language embedded in the document +[Cucumber][] is a tool for running test suites written in [Gherkin][]. + +Subplot is in some ways very similar to Cucumber and Gherkin, and +borrows heavily from them. However, our primary emphasis is not the +automated tests, but building mutual understanding among the +stakeholders of a system. + +# How does Subplot use AI or large language models? + +It doesn't. -- cgit v1.2.1