docs: explain approach for verification scenarios

Sponsored-by: author

1 files changed, 11 insertions, 2 deletions

diff --git a/riki.md b/riki.md
index 1725109..3ae21b2 100644
--- a/riki.md
+++ b/riki.md
@@ -1,5 +1,5 @@
 ---
-title: riki statis site generator
+title: riki static site generator
 subtitle: Subset of ikiwiki rewritten in Rust
 bindings:
 - subplot/riki.yaml
@@ -11,14 +11,23 @@ impls:
 ...
 
 [ikiwiki]: http://ikiwiki.info/
+[Subplot]: https://subplot.tech/
 
 # Introduction
 
 `riki` is a small subset of [ikiwiki][] rewritten in Rust, for
-speed.
+speed. This document describes the requirements and acceptance
+criteria for the software, and how to verify that riki meets them in
+an automated way. This is done using the [Subplot][] software.
 
 # Verification scenarios
 
+The approach used for verifying acceptance criteria is to run `riki`
+against known inputs, and check that the output is as expected.
+Specifically this is done by comparing the Pandoc abstract syntax
+trees of the input and output. Pandoc is a well-known, well-respected
+tool that we rely on as an "oracle".
+
 ## Markdown features
 
 ### Empty Markdown file