From d221840ee1d424b7cb0b862e3163badea1b25a7b Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 27 Jul 2019 15:39:39 +0300 Subject: Add: section on the motivation for Fable --- fable-arch.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'fable-arch.md') 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 -- cgit v1.2.1