# Introduction

  - who is this manual for?
  - what is Subplot meant for?
  - who is Subplot meant for?
  - history of Subplot
  - public use cases of Subplot

# Terminology

In Subplot we use the following terminology:

* A **need** (or "want" or "ask" or "request"): what a _stakeholder_
  wants from the system at the level they are concerned. This is often
  fuzzy, vague, and unclear and there may not be any way to verify
  that is is met.

  This is what a client tells a salesperson during the sales process,
  or an open source user says in a wishlist bug report.
  
  For example: a client might ask for the backup program to
  de-duplicate data in the backups; this is too vague to be
  implemented with any confidence. It leaves open too many details:
  what kind of data should be de-duplicated? At what granularity?
  Should it happen for data across users, and if so, how much can
  users know about each others' data? Should the de-duplication happen
  on the client machines, on the server, or only in storage?

* **Acceptance criteria:** needs expressed in a way that are clear,
  unambiguous, and specific, and with a specified way for verifying
  the criteria are met.

  This is what is nailed down in the contract so that it's clear when
  payment is due; or what an open source project commits to
  supporting.

* **Stakeholder:** anyone whose opinion about the system matters and
  who gets to affect what the acceptance criteria are, for their level of
  involvement. Stakeholders can be involved at various levels in a
  project. While the levels will vary between projects, they might be
  something like:
  
  * very high level: I am the CEO of the client, and I have final say
    on what we're willing to pay for, and I set the acceptance
    criteria that the system can back up all our important files on
    production systems; this will be verified by backing up all our
    production data.

  * medium level: I am the CTO of the client and I add the following
    acceptance criteria:
    
    - backed up data can be restored, verified by restoring a backup
      and comparing to the original data
    - backups are encrypted, verified by checking the backup for
      cleartext data
    - a full backup and restore of a terabyte of data takes at most
      one hour in a setup similar to our intended production systems,
      verified by measuring the backup and restore of production data

  * low level: I am the security analyst at the client and I add the
    acceptance criteria that the encryption uses SHA3 for integrity
    checking and the Ed25519 elliptic curve for encryption and digital
    signatures; these will be verified by third party inspection

* **Requirements:** since acceptance criteria are about the
  stakeholders accepting the software that gets offered to them, the
  development organization may use these criteria as a basis from
  which to derive more granular and specific statements about what the
  project should do and how to check that it does so. These are the
  traditional requirements and unit/integration tests which most
  software developers work with.
 

# An overview of acceptance criteria and their verification

  - discuss acceptance criteria vs requirements; functional vs
    non-functional requirements; automated vs manual testing
  - discuss stakeholders
  - discuss different approaches for verifying that a system meets it
    criteria
  - discuss how scenarios can be used to verify acceptance criteria

# Simple example project

  - discuss how to use Subplot for some simple, but not simplistic,
    software project
  - discuss different kinds of stakeholders a project may have

# Authoring Subplot documents

  - discuss that it may be necessary to have several documents for
    different audiences, at different levels of abstraction (cf. the
    FOSDEM safety devroom talk)
  - discuss writing style to target all the different stakeholders
  - discuss mechanics and syntax
    - Markdown and supported features
    - scenarios, embedded files, examples
    - bindings
    - step implementations in various languages
    - embedded markup for diagrams
    - running docgen

# Extended example project

  - discuss how to use Subplot for a significant project, but keep it
    sufficiently high level that it doesn't get too long and tedious
    to read

# Appendix: Implementing scenario steps in Bash

  - this appendix will explain how to implement scenario steps using
    the Bash shell

# Appendix: Implementing scenario steps in Python

  - this appendix will explain how to implement scenario steps using
    the Python language

# Appendix: Implementing scenario steps in Rust

  - this appendix will explain how to implement scenario steps using
    the Rust language


# Appendix: Scenario

This is currently necessary so that codegen won't barf.

~~~scenario
when I run true
~~~