docs: flesh out the FAQ

Sponsored-by: author

1 files 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.