Working on glossary

risk-first · Jun 24, 2024 · ae83e02 · ae83e02
1 parent 4203900
commit ae83e02
Show file tree

Hide file tree

Showing 24 changed files with 2,322 additions and 395 deletions.
diff --git a/docs/estimating/Fixing-Scrum.md b/docs/estimating/Fixing-Scrum.md
@@ -29,7 +29,7 @@ Work in Scrum is done within periods of time called _Sprints_.  Each sprint ends
 
 > "The goal of this activity is to inspect and adapt the product being built... Everyone in attendance gets clear visibility into what is occurring and has an opportunity to help guide the forthcoming development to ensure that the most business-appropriate solution is created." - Essential Scrum (p26), _Rubin_
 
-In Risk-First, we tend to call this validation step [Meeting Reality](/thinking/Glossary.md#meet-reality):  you are creating a [feedback loop](/thinking/Cadence.md) in order to minimise risk.  What is the risk you are minimising?  Essentially, we are trying to reduce the risk of the developers _building the wrong thing_, which could be due to misunderstanding of requirements, or perfectionism, or because the piece of work was ill-conceived in the first place.  In Risk-First, the risk of building the wrong thing is called [Feature Risk](/tags/Feature-Risk).
+In Risk-First, we tend to call this validation step [Meeting Reality](/tags/Meeting-Reality):  you are creating a [feedback loop](/thinking/Cadence.md) in order to minimise risk.  What is the risk you are minimising?  Essentially, we are trying to reduce the risk of the developers _building the wrong thing_, which could be due to misunderstanding of requirements, or perfectionism, or because the piece of work was ill-conceived in the first place.  In Risk-First, the risk of building the wrong thing is called [Feature Risk](/tags/Feature-Risk).
 
 ![Feature Risk mitigated by Meeting Reality](/img/generated/estimating/scrum/scrum1.png)
 
@@ -123,7 +123,7 @@ How can we, as software developers, minimise the chance of building the wrong th
 
 Look above at the diagram what Scrum is trying to do to mitigate [Feature Risk](/tags/Feature-Risk):
 
-- We [Meet Reality](/thinking/Glossary.md#meet-reality) to ensure we've got a feedback loop.
+- We [Meet Reality](/tags/Meeting-Reality) to ensure we've got a feedback loop.
 - We **time-box** to avoid wasting stake-holders' time (Schedule Risk).
 - We do **planning poker** to try and avoid the Coordination Risk problem of everyone needing to complete their work for the end of the Sprint.
 

diff --git a/docs/estimating/Fractals.md b/docs/estimating/Fractals.md
@@ -73,12 +73,12 @@ Releasing the first version might fill in some of the blanks, and show you more
 
 ![Third Version](/img/estimates/fractal4.png)
 
-As you go on [Meeting Reality](/thinking/Glossary.md#meet-reality), the shape of the problem domain comes into focus, and you're able to _refine_ your solution to match it more exactly.
+As you go on [Meeting Reality](/tags/Meeting-Reality), the shape of the problem domain comes into focus, and you're able to _refine_ your solution to match it more exactly.
 
 Is it possible to estimate problems in the Fractal Shape domain?  The best you might be able to do is to match two competing objectives:
 
 - Building Product:  By building functionality you head towards your [Goal](/thinking/Glossary.md#goal) on the [Risk Landscape](/thinking/Glossary.md#risk-landscape).  But how do you know this is the right goal?
-- [Meeting Reality](/thinking/Glossary.md#meet-reality):  By putting your product "out there" you find your customers and your niche in the market, and you explore the [Risk Landscape](/thinking/Glossary.md#risk-landscape).  But this takes time and effort away from _building product_.
+- [Meeting Reality](/tags/Meeting-Reality):  By putting your product "out there" you find your customers and your niche in the market, and you explore the [Risk Landscape](/thinking/Glossary.md#risk-landscape).  But this takes time and effort away from _building product_.
 
 With this in mind, you estimate a useful amount of time to go round this cycle, fixing the time but letting the deliverable vary.
 

diff --git a/docs/estimating/Risk-First-Analysis.md b/docs/estimating/Risk-First-Analysis.md
@@ -20,7 +20,7 @@ tweet: yes
 
 The previous article, [Fixing Scrum](Fixing-Scrum.md), examined Scrum's idea of "Sprints" and concluded:
 
-- The main purpose of a Sprint is to ensure there is a **feedback loop**.  Every two weeks (or however long the Sprint is) we have a Sprint Review, and review the code that has been completed during the Sprint.  In Risk-First parlance, we call this [Meeting Reality](/thinking/Glossary.md#meet-reality).  It is the process of _testing your ideas against reality_ to make sure they stand up. 
+- The main purpose of a Sprint is to ensure there is a **feedback loop**.  Every two weeks (or however long the Sprint is) we have a Sprint Review, and review the code that has been completed during the Sprint.  In Risk-First parlance, we call this [Meeting Reality](/tags/Meeting-Reality).  It is the process of _testing your ideas against reality_ to make sure they stand up. 
 
 - This Sprint Review is performed by the whole team.  All the code must be completed by the end of the sprint in order that it can be reviewed.  This introduces an artificial deadline to be met.
 

diff --git a/docs/risks/Communication-Risks/Learning-Curve-Risk.md b/docs/risks/Communication-Risks/Learning-Curve-Risk.md
@@ -29,5 +29,5 @@ By now it should be clear that it's going to be _both_ quite hard to read and wr
 But now we should be able to see the reason why it's harder to read than write too: 
 
  - When reading code, you are having to shift your [Internal Model](/thinking/Glossary.md#internal-model) to wherever the code is, accepting decisions that you might not agree with and accepting counter-intuitive logical leaps.  i.e. [Learning Curve Risk](/tags/Learning-Curve-Risk). _(cf. [Principle of Least Surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment))_
- - There is no [Feedback Loop](/thinking/Glossary.md#feedback-loop) between your [Internal Model](/thinking/Glossary.md#internal-model) and the [Reality](/thinking/Glossary.md#meet-reality) of the code, opening you up to [misinterpretation](Communication-Risk.md#misinterpretation).  When you write code, your compiler and tests give you this.
+ - There is no [Feedback Loop](/thinking/Glossary.md#feedback-loop) between your [Internal Model](/thinking/Glossary.md#internal-model) and the [Reality](/tags/Meeting-Reality) of the code, opening you up to [misinterpretation](Communication-Risk.md#misinterpretation).  When you write code, your compiler and tests give you this.
  - While reading code _takes less time_ than writing it, this also means the [Learning Curve](/tags/Learning-Curve-Risk) is steeper.
diff --git a/docs/risks/Complexity-Risk.md b/docs/risks/Complexity-Risk.md
@@ -13,7 +13,8 @@ tags:
  - Complexity Risk
  - Abstraction
 definitions:
- - Abstraction
+ - name: Abstraction
+   description: blah
 part_of: Operational Risk
 ---
 

diff --git a/docs/risks/Dependency-Risks/Agency-Risks/Agency-Risk.md b/docs/risks/Dependency-Risks/Agency-Risks/Agency-Risk.md
@@ -9,7 +9,8 @@ tags:
  - Agency Risk
  - Agent
 definitions: 
- - Agent
+ - name: Agent
+   description: blah
 featured: 
   class: c
   element: '<risk class="agency" />'

diff --git a/docs/risks/Risk-Landscape.md b/docs/risks/Risk-Landscape.md
@@ -8,6 +8,7 @@ tags:
 definitions:
  - name: Risk Landscape
    description: A hypothetical landscape on which risks can be placed. Taking Action means making a move on the Risk Landscape to reposition a project so that it has a different profile of Attendant Risks.
+   own_term: true
 
 featured: 
   class: c

diff --git a/docs/tags.yml b/docs/tags.yml
@@ -366,10 +366,6 @@ Extreme Programming:
   label: "Legal Risk"
   permalink: "Legal-Risk"
 
-"Meet Reality":
-  label: "Meet Reality"
-  permalink: "Meet-Reality"
-
 "Method":
   label: "Method"
   permalink: "Method"

diff --git a/docs/thinking/A-Simple-Scenario.md b/docs/thinking/A-Simple-Scenario.md
@@ -2,26 +2,27 @@
 title: A Simple Scenario
 description: What is the one thing every project needs to control to be successful?
 
-
 tags: 
  - Take Action
  - Internal Model
  - Goal
  - Attendant Risk
  - Hidden Risk
  - Meeting Reality
+ - Risk
 
 definitions:
  - name: Attendant Risk
    description:  A Risk you expect to face as the result of Taking Action.
    anchor: attendant-risks
+   own_term: true
  - name: Hidden Risk
    description: Risks you aren't aware of when you consider Taking Action. i.e. an unknown unknown.
    anchor: hidden-risks
+   own_term: true
  - name: Goal
    description: A picture of the future that an individual or team carries within their Internal Model; An imagined destination on the Risk Landscape. A specific Upside Risk we'd like to nurture and realize.
    anchor: goal-in-mind
-
 featured: 
   class: bg3
   element: '<risk href="/public/templates/risk-first/redesign/risks/goal_v2.svg"><code>Goal</code><title>A Simple Scenario</title></risk>'
@@ -73,7 +74,7 @@ As the dinner party gets closer, we make our preparations and the inadequacies o
 
 ![How Taking Action affects Reality, and also changes your Internal Model](/img/generated/introduction/model_vs_reality.png)
 
-Our model is forced to [Meet Reality](/thinking/Glossary.md#meet-reality), and the model changes,  forcing us to deal with these risks, as shown in the diagram above.  
+Our model is forced to [Meet Reality](/tags/Meeting-Reality), and the model changes,  forcing us to deal with these risks, as shown in the diagram above.  
 
 In Risk-First, whenever we try to _do something_ about a risk, it is called [Taking Action](/thinking/Glossary.md#taking-action).  [Taking Action](/thinking/Glossary.md#taking-action) _changes_ reality, and with it your [Internal Model](/thinking/Glossary.md#internal-model) of the risks you're facing.  That's because it's only by interacting with the world that we add knowledge to our [Internal Model](/thinking/Glossary.md#internal-model) about what works and what doesn't.  Even something as passive as _checking the shop opening times_ is an action, and it improves on our [Internal Model](/thinking/Glossary.md#internal-model) of the world.
 
@@ -89,9 +90,10 @@ I know that as a reader it's annoying to have to pick up new terminology.  So yo
 
 ## On To Software?
 
-Here, we've introduced some new terms that we're going to use a lot and, we've applied them in a simple scenario. Let's go over them again: 
+Here, we've introduced some new terms that we're going to use a lot and, we've applied them in a simple scenario.
 
 <BoxOut title="New Terms" link="/thinking/Glossary" linkText="View Glossary">
+Risk-First tries as far as possible to use pre-existing terminology from the world of risk management, however sometimes new terms are necessary.  This box summarises the terms introduced in this chapter and  where it's a term Risk-First introduces, I've added a label to alert you to this novelty.  
 <TermList details={frontMatter} /> 
 </BoxOut>
 

diff --git a/docs/thinking/Consider-Payoff.md b/docs/thinking/Consider-Payoff.md
@@ -30,7 +30,6 @@ definitions:
  - name: Expected Return 
    description: The probability-weighted return of the bet.
    anchor: the-structure-of-a-bet
-
 sidebar_position: 10
 tweet: yes
 ---
@@ -101,7 +100,7 @@ Sometimes, there will be multiple _actions_ you could take on a project and you
 - And, making a decision takes time, which could add risk to your schedule.
 - And what's the risk if the decision doesn't get made?
 
-The fruits of this gambling are revealed when we [meet reality](/thinking/Glossary.md#meet-reality) and we can see whether our bets were worthwhile.
+The fruits of this gambling are revealed when we [meet reality](/tags/Meeting-Reality) and we can see whether our bets were worthwhile.
 
 Very occasionally, you'll be in a place where your hand is forced and you have to take one of only a handful of actions, or there is a binary decision.  A so called "rock and a hard place".  But as we'll see in the third example below, even here you can usually change the action (and therefore the payoff) in your favour.   
 

diff --git a/docs/thinking/De-Risking.md b/docs/thinking/De-Risking.md
@@ -12,6 +12,7 @@ tags:
 definitions:
  - name: Take Action
    description: Refers to any activity in the project. Actions are taken in order to manage some risk. At the same time, Taking Action usually means interacting with reality and updating the Internal Model.
+   anchor: what-is-taking-action
 sidebar_position: 8
 redirect_from: 
  - /De-Risking
@@ -22,6 +23,8 @@ tweet: yes
 
 In this section, we're going to more closely at what, so far, we've called "[Taking Action](Glossary.md#taking-action)" and separate out different ways this can be done.   We'll introduce the correct risk management terms and give examples of how to apply these to software development.
 
+## What is Taking Action?
+
 So far in Risk-First, we've talked about [Taking Action](Glossary.md#taking-action) as having two effects:
 
  1. It's the way in which we [Meet Reality](Glossary.md#meet-reality) to learn about the world and uncover [Hidden Risks](Glossary.md#hidden-risk).

diff --git a/docs/thinking/Development-Process.md b/docs/thinking/Development-Process.md
@@ -69,7 +69,7 @@ We can all see this might end in disaster, but why?
 
 Two reasons: 
 
-1.  You're [Meeting Reality](/thinking/Glossary.md#meet-reality) all-in-one-go:  all of these risks materialize at the same time, and you have to deal with them all at once.
+1.  You're [Meeting Reality](/tags/Meeting-Reality) all-in-one-go:  all of these risks materialize at the same time, and you have to deal with them all at once.
 2.  Because of this, at the point you put code into the hands of your users, your [Internal Model](/thinking/Glossary.md#internal-model) is at its least-developed.  All the [Hidden Risks](/thinking/Glossary.md#hidden-risk) now need to be dealt with at the same time, in production.
 
 ## Applying the Toy Process
@@ -105,7 +105,7 @@ In the process of doing this, the BA is turning the simple feature request _idea
 
 In surfacing these risks, there is another outcome:  while **Feature X** might be flawed as originally presented, the BA can "evolve" it into a specification and tie it down sufficiently to reduce the risks.   The BA does all this by simply _thinking about it_, _talking to people_ and _writing stuff down_.
 
-This process of evolving the feature request into a requirement is the BA's job.  From our Risk-First perspective, it is _taking an idea and making it [Meet Reality](/thinking/Glossary.md#meet-reality)_.  Not the _full reality_ of production (yet), but something more limited.  
+This process of evolving the feature request into a requirement is the BA's job.  From our Risk-First perspective, it is _taking an idea and making it [Meet Reality](/tags/Meeting-Reality)_.  Not the _full reality_ of production (yet), but something more limited.  
 
 ### Code And Unit Test
 

diff --git a/docs/thinking/Meeting-Reality.md b/docs/thinking/Meeting-Reality.md
@@ -11,15 +11,16 @@ tags:
  - Take Action
  - Risk Landscape
  - Payoff
- - Meet Reality
+ - Meeting Reality
  - Internal Model
 definitions:
- - name: Meet Reality
-   description: Any moment where we test an Internal Model by exposing it's predictive power against reality. 
+ - name: Meeting Reality
+   description: Testing out the predictive power of an Internal Model by exposing it to reality. 
+   own_term: true
  - name: Internal Model
    description: The model of reality held by an individual, team, software system or other Agent. 
    anchor: different-internal-models
-
+   own_term: true
 sidebar_position: 4
 redirect_from: 
  - /Meeting-Reality

diff --git a/docs/thinking/Risk-First-Diagrams.md b/docs/thinking/Risk-First-Diagrams.md
@@ -51,6 +51,8 @@ In the middle of a Risk-First diagram we see the actions you could take.  In the
 
 ### On The Right
 
+![Outcomes](/img/generated/introduction/outcome.png)
+
 _Nothing comes for free._  On the right, you can see the consequence or outcome of the actions you've taken:  [Attendant Risks](/thinking/Glossary.md#attendant-risk) are the _new_ risks you now have as a result of taking the action.
 
 Hosting a dinner party opens you up to attendant risks like "Not Enough to Eat".  As a result of that risk, we consider buying lots of snacks.  As a result of _that_ risk, we start to consider whether our guests will be impressed with that.

diff --git a/src/images/generated/introduction/diagram_example.adl b/src/images/generated/introduction/diagram_example.adl
@@ -13,54 +13,33 @@
 				<code>Risk</code>
 				<title>Nothing To Eat</title>
 			</risk>
-			<description id="id_16">
+			<label id="id_16">
 				Internal Model
-			</description>
+			</label>
 		</container>
-		<description id="d1">Part A</description>
 	</group>
 	<group
 		style="--kite9-layout: down; --kite9-sizing: maximize; ">
 		<action id="a">Buy Snacks</action>
-		<description id="d2">Part B</description>
-
 	</group>
 	<group  style="--kite9-layout: down; ">
 
-		<container bordered="true" id="c-zr"
-			style="--kite9-layout: down; ">
-			<group style="--kite9-layout: right; ">
-				<risk class="generic"
-					href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
-					id="id_0-ae">
-					<code>Risk</code>
-					<title>Too Many Leftovers</title>
-				</risk>
-				<risk class="generic"
-					href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
-					id="id_0-ry">
-					<code>Risk</code>
-					<title>Guests Are Unimpressed</title>
-				</risk>
-			</group>
+		<container bordered="true" id="c-zr">
+			<risk class="generic"
+				href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
+				id="id_0-ae">
+				<code>Risk</code>
+				<title>Too Many Leftovers</title>
+			</risk>
+			<risk class="generic"
+				href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
+				id="id_0-ry">
+				<code>Risk</code>
+				<title>Guests Are Unimpressed</title>
+			</risk>
 			<label id="id_16-nm">
 				Updated Internal Model
 			</label>
 		</container>
-		<description id="d3">Part C</description>
-
 	</group>
-
-	<align>
-		<from reference="id_0" />
-		<to reference="a" />
-	</align>
-	<align>
-		<from reference="d1" />
-		<to reference="d2" />
-	</align>
-	<align>
-		<from reference="d2" />
-		<to reference="d3" />
-	</align>
 </diagram>
diff --git a/src/images/generated/introduction/outcome.adl b/src/images/generated/introduction/outcome.adl
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<diagram
+	xslt:template="/public/templates/risk-first/risk-first-template.xsl"
+	xmlns="http://www.kite9.org/schema/adl"
+	xmlns:xslt="http://www.kite9.org/schema/xslt"
+	style="--kite9-min-width: 600pt;" id="diagram-113" name="Goal In Mind">
+
+	<container bordered="true" id="c-zx">
+		<risk class="attendant" id="id_0-lm">Nothing To Eat</risk>
+		<risk class="attendant" id="id_0-mi">Wrong Ingredients</risk>
+		<risk class="attendant" id="id_0-on">Ruin The Food</risk>
+		<label id="id_16-sq">
+			Consequences of inviting guests
+		</label>
+	</container>
+
+
+	<container bordered="true" id="c-zr">
+		<risk class="generic"
+			href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
+			id="id_0-ae">
+			<code>Risk</code>
+			<title>Too Many Leftovers</title>
+		</risk>
+		<risk class="generic"
+			href="/public/templates/risk-first/redesign/risks/attendant_risk_v2.svg"
+			id="id_0-ry">
+			<code>Risk</code>
+			<title>Guests Are Unimpressed</title>
+		</risk>
+		<label id="id_16-nm">
+			Consequences of buying snacks
+		</label>
+	</container>
+</diagram>