Skip to content

Commit e8ccc67

Browse files
jgelukjgeluk
committed
docs(concept): enhance story page with comprehensive improvements
- Add summary block for consistency with other concept pages - Expand Business & Management Audience tab: - Add What Is a Story? section - Add Story Structure section explaining Who/What/Why format - Add tip admonition about starting simple - Improve examples formatting - Add Why Stories Matter section - Significantly enhance Data & Tech Audience tab: - Add What Is a Story in the EKG Method? section - Add The Challenge section - Restructure Structured Business User Stories with subsections: Strategic Focus, Gap Analysis, Avoid Tunnel Thinking, Separation of Concerns, Testable Specifications - Add Continuous Testing and Functional Health section - Add Relationship to Other Concepts section - Remove TODO placeholders and replace with structured content - Add links to related concepts (Persona, Use Case, Outcome, Concept) - Ensure all lines under 70 characters
1 parent bf10d07 commit e8ccc67

File tree

1 file changed

+162
-61
lines changed

1 file changed

+162
-61
lines changed

‎docs/concept/story.md‎

Lines changed: 162 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,169 @@
11
# Story
22

3+
<!--summary-start-->
4+
_A structured business requirement expressed in plain language that
5+
defines what a Persona needs to accomplish within a Use Case_
6+
<!--summary-end-->
7+
38
=== "Business & Management Audience"
49

5-
A Story --- in the context of a [Use Case](use-case.md) in the
6-
[Use Case Tree](use-case-tree.md) --- defines a business requirement.
7-
8-
A business user could specify a requirement as follows:
9-
10-
- _As the Chief Risk Officer, I need to know our current Risk Position against party B, so that I can Assess the Risk_
11-
- _As an Auditor, I need to get a list of all current board members of legal entity X, so that I can Verify Stakeholders_
12-
- _As an Employee, I need to get a list of all my colleagues in my unit, so that I Know my Colleagues_
13-
- _As a customer, I need to get a list of all products, so that I can make a product selection_
14-
15-
And so forth. That's all we ask in the early phases of a given use case.
16-
10+
## What Is a Story?
11+
12+
A **Story** — in the context of a [Use Case](use-case.md) in the
13+
[Use Case Tree](use-case-tree.md) — defines a business
14+
requirement.
15+
It captures what someone needs to accomplish, expressed in their
16+
own language.
17+
18+
## Story Structure
19+
20+
Stories follow a simple, structured format that captures three
21+
essential elements:
22+
23+
- **Who** — The [Persona](persona.md) who needs this capability
24+
(e.g., "As the Chief Risk Officer...")
25+
- **What** — What they need to do or know (e.g., "...I need to
26+
know our current Risk Position...")
27+
- **Why** — The business [Outcome](outcome.md) or purpose (e.g.,
28+
"...so that I can Assess the Risk")
29+
30+
!!! tip "Start simple"
31+
32+
In the early phases of a use case, we only ask for these
33+
three elements.
34+
Don't worry about how it will be implemented — that comes
35+
later.
36+
37+
## Examples
38+
39+
A business user could specify requirements as follows:
40+
41+
- _As the Chief Risk Officer, I need to know our current Risk
42+
Position against party B, so that I can Assess the Risk_
43+
- _As an Auditor, I need to get a list of all current board
44+
members of legal entity X, so that I can Verify Stakeholders_
45+
- _As an Employee, I need to get a list of all my colleagues in
46+
my unit, so that I Know my Colleagues_
47+
- _As a customer, I need to get a list of all products, so that
48+
I can make a product selection_
49+
50+
And so forth.
51+
That's all we ask in the early phases of a given use case.
52+
53+
## Why Stories Matter
54+
55+
Stories provide a bridge between business needs and technical
56+
implementation.
57+
They ensure that:
58+
59+
- **Business language is preserved** — Requirements are captured
60+
in terms the business understands
61+
- **Focus stays on outcomes** — We understand the "why" behind
62+
each requirement
63+
- **Everyone is aligned** — Business, data, and technology
64+
teams share a common understanding of what needs to be
65+
delivered
66+
1767

1868
=== "Data & Tech Audience"
1969

20-
"User Stories" start out as plain English sentences that, as the name suggests, come from the user.
21-
In other words, "the Business" or "the Customer", the end user of a system or application, is
22-
responsible for explaining to the people who need to deliver that system what the system is supposed to do.
23-
24-
Makes sense right? Unfortunately, it's usually not that simple.
25-
All kinds of other factors come into play that have nothing to do with specifying what the user
26-
_really_ wants such as design, architecture, existing systems, budgets, time, regulations, policies
27-
and technical capabilities.
28-
29-
However, it is a good thing to at least capture the "real" wishes of the user without having to consider all of
30-
those other aspects.
31-
Where the challenge is to ask the user to step out of their normal day-to-day practices and comfort zone and to
32-
think ahead in a way that is not restricted by all the daily hurdles and practicalities.
33-
This method proposes to use "Structured Business User Stories" to achieve many things such as:
34-
35-
* have a more strategic view on which functionality is ^^really^^ required
36-
* allow to see "the disconnect" or "the gap" between what's required and what is currently available,
37-
delivered and deliverable
38-
* avoid "tunnel thinking" where everyone, especially also "the business" itself, makes all kinds of
39-
assumptions that may or may not be true and could severely diminish creativity.
40-
* create a clear separation of concerns: the business specifies what they need but leaves it to the
41-
data and technology people to work out how they can deliver it.
42-
So no more "screen designs" (that comes later) or "schema's" that are used as
43-
"functional specification".
44-
We need to be able to go deeper, to the core questions about **"what do you ^^really^^ need?"**
45-
(and forget about the "How" for a minute).
46-
* have clear testable specifications of required functionality for the whole life-cycle of a given
47-
user story.<br/>
48-
As long as people need a given story to be implemented, it will continuously be tested "end-to-end",
49-
from inception all the way to production, not only before deployment into production but actually
50-
also in production itself.
51-
The EKG knows about "its Stories" and continuously tests them, it therefore knows about its own
52-
"functional health" and can detect whenever something changes (code, ontologies, ETL, new policies)
53-
whether it can still deliver all functionality
54-
55-
Here's a diagram that illustrates how we can break up a user story in some interesting components that
56-
we can link to other data structures in the Knowledge Graph such as a taxonomy of all ["Personas"](persona.md)
57-
58-
<figure markdown>
59-
TODO
60-
</figure>
61-
62-
Here's one example of a User Story, more examples will follow later:
63-
64-
<figure markdown>
65-
TODO
66-
</figure>
67-
68-
70+
## What Is a Story in the EKG Method?
71+
72+
"User Stories" start out as plain English sentences that, as the
73+
name suggests, come from the user.
74+
In other words, "the Business" or "the Customer" — the end user
75+
of a system or application — is responsible for explaining to
76+
the people who need to deliver that system what the system is
77+
supposed to do.
78+
79+
Makes sense, right?
80+
Unfortunately, it's usually not that simple.
81+
All kinds of other factors come into play that have nothing to
82+
do with specifying what the user _really_ wants, such as design,
83+
architecture, existing systems, budgets, time, regulations,
84+
policies, and technical capabilities.
85+
86+
## The Challenge
87+
88+
However, it is a good thing to at least capture the "real"
89+
wishes of the user without having to consider all of those other
90+
aspects.
91+
The challenge is to ask the user to step out of their normal
92+
day-to-day practices and comfort zone and to think ahead in a
93+
way that is not restricted by all the daily hurdles and
94+
practicalities.
95+
96+
## Structured Business User Stories
97+
98+
This method proposes to use "Structured Business User Stories"
99+
to achieve many things:
100+
101+
### Strategic Focus
102+
103+
Have a more strategic view on which functionality is **really**
104+
required.
105+
By focusing on business outcomes rather than implementation
106+
details, we can identify what truly matters.
107+
108+
### Gap Analysis
109+
110+
Allow seeing "the disconnect" or "the gap" between what's
111+
required and what is currently available, delivered, and
112+
deliverable.
113+
This helps prioritize work and identify areas where new
114+
capabilities are needed.
115+
116+
### Avoid Tunnel Thinking
117+
118+
Avoid "tunnel thinking" where everyone, especially "the business"
119+
itself, makes all kinds of assumptions that may or may not be true
120+
and could severely diminish creativity.
121+
Stories encourage thinking beyond current constraints.
122+
123+
### Separation of Concerns
124+
125+
Create a clear separation of concerns: the business specifies what
126+
they need but leaves it to the data and technology people to
127+
work out how they can deliver it.
128+
So no more "screen designs" (that comes later) or "schemas" that
129+
are used as "functional specification".
130+
We need to be able to go deeper, to the core questions about
131+
**"what do you really need?"** (and forget about the "How" for a
132+
minute).
133+
134+
### Testable Specifications
135+
136+
Have clear testable specifications of required functionality for
137+
the whole lifecycle of a given user story.
138+
As long as people need a given story to be implemented, it will
139+
continuously be tested "end-to-end," from inception all the way
140+
to production, not only before deployment into production but
141+
actually also in production itself.
142+
143+
## Continuous Testing and Functional Health
144+
145+
The EKG knows about "its Stories" and continuously tests them.
146+
It therefore knows about its own "functional health" and can
147+
detect whenever something changes (code, ontologies, ETL, new
148+
policies) whether it can still deliver all functionality.
149+
150+
This means that Stories are not just requirements documents —
151+
they are **living, executable specifications** that the EKG
152+
monitors and validates throughout their entire lifecycle.
153+
154+
## Relationship to Other Concepts
155+
156+
Stories link to other data structures in the Knowledge Graph:
157+
158+
- **[Personas](persona.md)** — Each Story specifies which
159+
Persona needs the capability
160+
- **[Use Cases](use-case.md)** — Stories are organized within
161+
Use Cases, defining the functional requirements
162+
- **[Outcomes](outcome.md)** — The "why" part of a Story links
163+
to business outcomes
164+
- **[Concepts](concept.md)** — Stories reference domain concepts
165+
that need to be understood and modeled
166+
167+
This integration ensures that Stories are not isolated
168+
requirements but part of a cohesive, semantic model of the
169+
enterprise.

0 commit comments

Comments
 (0)