diff options
author | Daniel Silverstone <dsilvers+gitlab@digital-scurf.org> | 2022-11-09 08:34:32 +0000 |
---|---|---|
committer | Daniel Silverstone <dsilvers+gitlab@digital-scurf.org> | 2022-11-09 08:34:32 +0000 |
commit | c0ed7a3b60ad7b98fb7953443a0e0cceb2298666 (patch) | |
tree | 4bfda7936e0ee852b81c4026ba0cab839d241e9f | |
parent | 0d2ab1a2686f1abc624e61b1331d3fce78e31002 (diff) | |
parent | df760f6c2a95a072e9ba3cd6a5fa11b4d921624c (diff) | |
download | subplot-c0ed7a3b60ad7b98fb7953443a0e0cceb2298666.tar.gz |
Merge branch 'liw/book' into 'main'
docs: add placeholder for a user guide for Subplot
Closes #291
See merge request subplot/subplot!299
-rw-r--r-- | book/user-guide.md | 66 | ||||
-rw-r--r-- | book/user-guide.subplot | 10 |
2 files changed, 76 insertions, 0 deletions
diff --git a/book/user-guide.md b/book/user-guide.md new file mode 100644 index 0000000..2e19b84 --- /dev/null +++ b/book/user-guide.md @@ -0,0 +1,66 @@ +# Introduction + + - who is this manual for? + - what is Subplot meant for? + - who is Subplot meant for? + - history of Subplot + - public use cases of Subplot + +# 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 /bin/true +~~~ diff --git a/book/user-guide.subplot b/book/user-guide.subplot new file mode 100644 index 0000000..2c60f19 --- /dev/null +++ b/book/user-guide.subplot @@ -0,0 +1,10 @@ +title: "Subplot user guide" +authors: + - The Subplot project +markdowns: + - user-guide.md +bindings: + - lib/runcmd.yaml +impls: + python: + - lib/runcmd.py |