summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2019-07-27 15:39:39 +0300
committerLars Wirzenius <liw@liw.fi>2019-07-27 15:39:39 +0300
commitd221840ee1d424b7cb0b862e3163badea1b25a7b (patch)
tree94b746342b9e18369a584b68d7fe740a2a32cad1
parentedfbe4331e4f444ee9f51cd02e24fbc03ac3182f (diff)
downloadfable-poc-d221840ee1d424b7cb0b862e3163badea1b25a7b.tar.gz
Add: section on the motivation for Fable
-rw-r--r--fable-arch.md38
1 files changed, 38 insertions, 0 deletions
diff --git a/fable-arch.md b/fable-arch.md
index 45f120c..c25f825 100644
--- a/fable-arch.md
+++ b/fable-arch.md
@@ -56,6 +56,44 @@ documented in a number of source files, which by two Fable tools. One
tool produces a PDF or HTML document, for humans to read. The other
produces a test program, which executes the acceptaance tests.
+## Motivation for Fable
+
+Keeping track of requirements and acceptance criteria is necessary for
+all but the simplest of software projects. Having all stakeholders in
+a projects agree to them is crucial, as is that all agree how it is
+verified that the software meets the acceptance criteria. Fable aims
+to provide a way for documenting the shared understanding of what the
+acceptance criteria are and how they can be checked automatically.
+
+Stakeholders in a project may include:
+
+* those who pay for the work to be done; this may be the employer of
+ the developers for in-house projects ("customer")
+* those who use the resultint software, whether they pay for it or not
+ ("user")
+* those who install and configure the softare and keep it functional
+ ("sysadmin")
+* those who support the users ("support")
+* those who develop the software in the first place ("developer")
+
+All stakeholders need to understand the acceptance criteria, and how
+the software is evaluated against them. In the simplest case, the
+customer and the developer need to both understand and agree so that
+the developer knows when the job is done, and the customer knows when
+they need to pay their bill.
+
+However, even when the various stakeholder roles all fall upon the
+same person, or only on people who act as developers, the Fable
+approach can be useful. A developer would understand acceptance
+criteria expressed only in code, but doing so may take time and energy
+that are not always available. The Fable approach aims to encourage
+hiding unnecessary detail and documenting things in a way that is easy
+to understand with little effort.
+
+Unfortunately, this does mean that for a Fable output document to
+be good and helpful, writing it will require effort and skill. No tool
+can replace that.
+
# Requirements
This chapter lists requirements for Fable. These requirements are not