|author||Lars Wirzenius <email@example.com>||2019-07-27 15:39:39 +0300|
|committer||Lars Wirzenius <firstname.lastname@example.org>||2019-07-27 15:39:39 +0300|
Add: section on the motivation for Fable
Diffstat (limited to 'fable-arch.md')
1 files changed, 38 insertions, 0 deletions
diff --git a/fable-arch.md b/fable-arch.md
index 45f120c..c25f825 100644
@@ -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
+* those who install and configure the softare and keep it functional
+* 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.
This chapter lists requirements for Fable. These requirements are not