Skip to content

Commit

Permalink
Fixing articles to make book build work
Browse files Browse the repository at this point in the history
  • Loading branch information
@robmoffat
robmoffat committed May 22, 2024
1 parent 3c0718e commit 45de7e7
Show file tree
Hide file tree
Showing 15 changed files with 3,707 additions and 39 deletions.
7 changes: 3 additions & 4 deletions docs/thinking/Cadence.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ In a software development scenario, you should also test your model against real

.. and so on.

### Time / Reality Trade-Off
## Time / Reality Trade-Off

This list is arranged so that at the top, we have the most visceral, most _real_ feedback loop, but at the same time, the slowest.

Expand All @@ -54,7 +54,7 @@ That'd be neat, eh? If you did have this, would there be any point at all in a

The whole _reason_ we have tools like compilers is because they give us a short-cut way to get some limited experience of reality _faster_ than would otherwise be possible. Because cadence is really important: the faster we test our ideas, the more quickly we'll find out if they're correct or not and the faster we can back out of the bets that aren't [paying off](Consider-Payoff.md)

### Development Cycle Time
## Development Cycle Time

Developers often ignore the fast feedback loops at the bottom of the list above because the ones nearer the top _will do_.

Expand All @@ -68,8 +68,7 @@ The [Testing Pyramid](http://www.agilenutshell.com/episodes/41-testing-pyramid)

![The Testing Pyramid](/img/generated/introduction/testing_pyramid.png)


### Production
## Production

You could take this section to mean that [Continuous Delivery](https://en.wikipedia.org/wiki/Continuous_delivery) (CD) is always and everywhere a good idea. That's not a bad take-away, but it's clearly more nuanced than that.

Expand Down
82 changes: 73 additions & 9 deletions docs/thinking/Consider-Payoff.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@ The table above summarises these terms. It's important that as developers, we t

| Result | Stake | Value | Expected Value (Value x Probability) | Expected Return (Expected Value / Stake) |
|:--------------------------------:|--------:|------:|--------------------------------------:|-----------------------------------------:|
| Win <br />(.5&nbsp;probability) | | £30 | £15 (£30 x .5) | |
| Lose <br />(.5&nbsp;probability) | | -£10 | -£5 (-£10 x .5) | |
| Win (.5&nbsp;probability) | | £30 | £15 (£30 x .5) | |
| Lose (.5&nbsp;probability) | | -£10 | -£5 (-£10 x .5) | |
| **Total** | **£10** | | **£10** | **100%** |

- **Expected Value**: The probability-weighted average value of the outcome. That is, the values of each outcome multiplied by their probabilities, added up. The table above shows this calculation for our bet coming out at £10.
Expand Down Expand Up @@ -118,13 +118,77 @@ Some people would argue that YAGNI is really a weapon to combat over-engineering

It's important to reflect on the fact that there are other factors at play here: people know they'll be judged on the quality of their work, don't want to make mistakes and might want to add tools or new skills to their CVs (all of which we'll cover in [Agency Risk](../risks/Agency-Risk.md). If you are running the development team, you need to be aware of this risk and work hard to minimise it.

| Example | Argument In Favour | "Do It Now" Expected Value | "Do It Later" Option Expected Value |
|--------------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Introducing Abstractions | "Feels like better engineering and future-proofing" | <ul><li>Doesn't get used immediately</li> <li>Up-front development time</li> <li>Adds complexity</li> <li>Harder to maintain</li><li>Unlikely to anticipate right abstractions</li> </ul> | <ul><li>Some re-work </li><li>Will reed to re-familiarise with the code</li></ul> |
| Beauty | "As software artiste, I'm searching for perfection..." | <ul> <li>Up-front development time</li> <li>Hard to decide the end point</li> </ul> | <ul><li>Code less well factored</li><li>Might be harder to work with and change</li> </ul> |
| 100% Coverage | "Feels perfect. I don't like to see the red." | <ul> <li>Up-front development time</li> </ul> | |
| Using Heavyweight tools | "We'll have to replace our simple version sooner or later" | <ul> <li>Learning curve time</li> <li>Adds complexity</li> <li>Harder to maintain</li> </ul> | <ul><li>Some re-engineering </li> </ul> |

![Over Engineering](/img/generated/introduction/over-engineering.svg)
<table>
<tr>
<th>Example</th>
<th>Argument In Favour </th>
<th>"Do It Now" Expected Value </th>
<th>"Do It Later" Option Expected Value</th>
</tr>
<tr>
<td>Introducing Abstractions</td>
<td>"Feels like better engineering and future-proofing"</td>
<td>
<ul>
<li>Doesn't get used immediately</li>
<li>Up-front development time</li>
<li>Adds complexity</li>
<li>Harder to maintain</li>
<li>Unlikely to anticipate right abstractions</li>
</ul>
</td>
<td>
<ul>
<li>Some re-work </li>
<li>Will reed to re-familiarise with the code</li>
</ul>
</td>
</tr>
<tr>
<td>100% Coverage </td>
<td>"Feels perfect. I don't like to see the red."</td>
<td>
<ul>
<li>Up-front development time</li>
</ul>
</td>
<td></td>
</tr>
<tr>
<td>Beauty</td>
<td>"As software artiste, I'm searching for perfection..."</td>
<td>
<ul>
<li>Up-front development time</li>
<li>Hard to decide the end point</li>
</ul>
</td>
<td>
<ul>
<li>Code less well factored</li>
<li>Might be harder to work with and change</li>
</ul>
</td>
</tr>
<tr>
<td>Using Heavyweight Tools </td>
<td> "We'll have to replace our simple version sooner or later"</td>
<td>
<ul>
<li>Learning curve time</li>
<li>Adds complexity</li>
<li>Harder to maintain</li>
</ul>
</td>
<td>
<ul>
<li>Some re-engineering</li>
</ul>
</td>
</tr>
</table>

With that caveat aside, it should be clear that the way to escape the over-engineering trap is to think hard about [Expected Value](Glossary.md#expected-value). The above table tries to capture the difference in [Expected Value](Glossary.md#expected-value) between "Doing it Now" versus having the _option to_ "Do it Later".

There is no hard and fast right answer here. Sometimes, it is correct to strive for 100% coverage or polish the code factorisation. But hopefully thinking about the choice in terms of these two alternatives is helpful.
Expand Down
2 changes: 1 addition & 1 deletion docs/thinking/De-Risking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ The table above lists a set of _generic strategies_ for derisking which we'll lo

1. **Delegating Responsibility**: Putting people in charge of specific risks shares or transfers the responsibility away from you. Note that inside organisations, transfer of risk can become a political game:

> "... ownership results in ‘one throat to choke’ for audit functions [and] from ownership comes responsibility. A lot of the political footwork in an enterprise revolves around trying to not own technologies. Who wants to be responsible for Java usage across a technology function of dozens of thousands of staff, any of whom might be doing crazy stuff? You first, mate. " - [Why Are Enterprises So Slow?, _zwischenzugs.com_](https://zwischenzugs.com/2018/10/02/why-are-enterprises-so-slow/)
> "... ownership results in ‘one throat to choke’ for audit functions (and) from ownership comes responsibility. A lot of the political footwork in an enterprise revolves around trying to not own technologies. Who wants to be responsible for Java usage across a technology function of dozens of thousands of staff, any of whom might be doing crazy stuff? You first, mate. " - [Why Are Enterprises So Slow?, _zwischenzugs.com_](https://zwischenzugs.com/2018/10/02/why-are-enterprises-so-slow/)
## Retain

Expand Down
12 changes: 12 additions & 0 deletions docs/thinking/Glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ Agency is the capacity of an actor to act in a given environment. We use the te

_See: [Agency Risk](../risks/Agency-Risk.md)_

### Anti-Goal

The opposite of a [Goal](#goal), that is, something you are working hard to avoid happening.

_See: [Goal (Tag)](/tags/goal)_

### Balance Of Risk

The distribution of possible returns, given the set of risks you face from your position on the [Risk Landscape](#risk-landscape).
Expand Down Expand Up @@ -86,6 +92,12 @@ Any moment where we test an [Internal Model](#internal-model) by exposing it's p

_See: [Meet Reality (Tag)](/tags/meet-reality)_

### Opportunity

A term often used instead of [Upside Risk](#upside-risk) as something you'd like to happen.

_See: [Upside Risk](#upside-risk)

### Payoff

Payoff refers to the _value_ of the [actions we take](#taking-action). When we decide on a course of action, we have in mind a risk we wish to manage. If the action is likely to have a big positive effect on the risk of a project, we say it has a promising payoff, whereas if the action fails to manage the risk, then it hasn't _paid off_.
Expand Down
14 changes: 12 additions & 2 deletions docs/thinking/Just-Risk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,11 @@ Let's look at a real-life example. The above image shows a selection of issues

## Goals Are Risks Too

In the previous sections, we introduced something of a "diagram language" of risk. Let's review it:
[Earlier](Risk-First-Diagrams.md), we introduced something of a "diagram language" of risk.

![Risk-First Diagram Language](/img/generated/introduction/all_risk_management_language.png)
![The Risk-First Diagram Language, with _stimulus_ on the left, the action (or _response_) we take in the middle, and the results on the right.](/img/generated/introduction/all_risk_management_language.png)

The above diagram is an idealised example of this, showing how we take action to address the risks and goals on the left and end up with new risks on the right.

[Goals](../thinking/Glossary.md#goal) live inside our [Internal Model](../thinking/Glossary.md#internal-model), just like Risks. Functionally, Goals and Risks are equivalent. For example, the Goal of "Implementing Feature X" is equivalent to mitigating "Risk of Feature X not being present".

Expand All @@ -118,6 +120,14 @@ From a redundancy perspective, if you know any two of the start, end or movement

But risks, goals and actions are deeply connected. By focusing on "Risk-First", we don't ignore the reasons we're doing something.

## On Opportunities

![Risks, Goals, Opportunities, Anti-goals](/img/generated/introduction/risks_opportunities.png)

Some literature talks about [Opportunities](Glossary.md#opportunity) as being the opposite of [Risks](Glossary.md#risk). Here, we tend to call these [Upside Risks](Glossary.md#upside-risk). Therefore, there is a related discipline of _opportunity management_.

Here, we're not going to get into this except to say that sometimes it is worth also considering the idea of [Anti-Goals](../misc/Anti-Goals.md): that is, being clear about the things you really want to avoid happening, as shown in the figure above.

## Summary

A Risk-First diagram represents a starting point (a risk, a goal), some movement (an action to take) and a destination (mitigated risk, completed goals, new attendant risks). But frequently our usual tools will only show us one of these parts: the RAID log is focusing on the starting point, and some actions (decisions). Issues (in an issue log) often focus on the action and possibly the risk. In a way, this is fine as you can derive the third by knowing the other two.
Expand Down
50 changes: 50 additions & 0 deletions src/images/generated/introduction/over-engineering.adl
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
<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" id="dia">

<table style="--kite9-text-bounds-width: 40pt; ">
<celltext style="--kite9-occupies: 0 0; text-align: center; font-weight: 800;">Example</celltext>
<celltext style="--kite9-occupies: 1 0; text-align: center; font-weight: 800;">Argument</celltext>
<celltext style="--kite9-occupies: 2 0; text-align: center; font-weight: 800;">"Do It Now"
Expected Value</celltext>
<celltext style="--kite9-occupies: 3 0; text-align: center; font-weight: 800;">"Do It Later"
Option Expected Value</celltext>

<celltext style="--kite9-occupies: 0 1; ">Introducing Abstractions</celltext>
<celltext style="--kite9-occupies: 1 1; ">"Feels like better
engineering and future-proofing"</celltext>
<celltext style="--kite9-occupies: 2 1; text-align: left; ">
&middot;Doesn't get used immediately
&middot;Up-front development time
&middot;Adds complexity
&middot;Harder to maintain
&middot;Unlikely to anticipate right abstractions
</celltext>
<celltext style="--kite9-occupies: 3 1; ">"Do It Later"
Option Expected Value</celltext>

<celltext style="--kite9-occupies: 0 2; ">100% Coverage </celltext>
<celltext style="--kite9-occupies: 1 2; ">"Feels perfect. I don't like to see the red."</celltext>
<celltext style="--kite9-occupies: 2 2; ">"Do It Now"
Expected Value</celltext>
<celltext style="--kite9-occupies: 3 2; ">"Do It Later"
Option Expected Value</celltext>

<celltext style="--kite9-occupies: 0 3; ">Beauty</celltext>
<celltext style="--kite9-occupies: 1 3; ">"As software artiste, I'm searching for perfection..."</celltext>
<celltext style="--kite9-occupies: 2 3; ">"Do It Now"
Expected Value</celltext>
<celltext style="--kite9-occupies: 3 3; ">"Do It Later"
Option Expected Value</celltext>

<celltext style="--kite9-occupies: 0 4; ">Using Heavyweight Tools</celltext>
<celltext style="--kite9-occupies: 1 4; ">"We'll have to replace our simple version sooner or later"</celltext>
<celltext style="--kite9-occupies: 2 4; ">"Do It Now"
Expected Value</celltext>
<celltext style="--kite9-occupies: 3 4; ">"Do It Later"
Option Expected Value</celltext>

</table>

</diagram>
17 changes: 17 additions & 0 deletions src/images/generated/introduction/risks_opportunities.adl
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<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" id="dia"
style="--kite9-layout: down; --kite9-min-width: 600pt; ">
<table k9-texture="none">
<celltext style="--kite9-occupies: 2 1; --kite9-padding: 20pt; text-align: center; " class="bold bottom">Accident</celltext>
<celltext style="--kite9-occupies: 3 1; --kite9-padding: 20pt; " class="bold bottom">Deliberate</celltext>

<celltext style="--kite9-occupies: 1 2; --kite9-padding: 20pt; " class="bold">Positive Outcome</celltext>
<celltext style="--kite9-occupies: 2 2; --kite9-padding: 20pt; " class="">Opportunity</celltext>
<celltext style="--kite9-occupies: 3 2; --kite9-padding: 20pt; " class="">Goal</celltext>
<celltext style="--kite9-occupies: 1 3; --kite9-padding: 20pt; " class="bold">Negative Outcome</celltext>
<celltext style="--kite9-occupies: 2 3; --kite9-padding: 20pt; " class="">Risk</celltext>
<celltext style="--kite9-occupies: 3 3; --kite9-padding: 20pt; " class="">Anti-Goal (Fear)</celltext>
</table>
</diagram>
Loading

0 comments on commit 45de7e7

Please sign in to comment.