Tech debt definition (#263)

Author: andyblundell

README.md

@@ -10,8 +10,8 @@ This framework is concerned with using "good" software engineering to support ra
 
 It aims to:
 1. Describe a shared (across multiple teams) definition of "good" engineering
-2. Provide tools for teams to gain insight into their current engineering maturity levels
-3. Provide resources to support teams to increase their engineering maturity levels
+2. Provide tools for teams to gain insight into their current engineering maturity levels and their level of [technical debt](tech-debt.md)
+3. Provide resources to support teams to increase their engineering maturity levels and manage their [technical debt](tech-debt.md)
 
 ![Ecosystem](images/engineering-ecosystem.png)
 ## Philosophy
@@ -21,7 +21,7 @@ The philosophy underpinning this framework advocates:
 * Empowered delivery teams which are accountable for their products
 * Products must be actively maintained for their entire lifecycle
 * Rapid, iterative and incremental development: "Release early. Release often. And listen to your customers." (Eric S. Raymond in [The Cathedral and the Bazaar](https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar))
-* Robust and comprehensive automation supporting and enforcing quality 
+* Robust and comprehensive automation supporting and enforcing quality
 * Reliable & scalable services, remembering "Everything fails, all the time" (Werner Vogels), and treating operations as a software engineering challenge (as in Google's [Site Reliability Engineering](https://landing.google.com/sre/))
 * Loosely-coupled & cloud-native composable components as the default mode of construction
 * Continuous improvement, with prioritisation decisions based on data rather than sentiment

continuous-improvement.md

@@ -54,13 +54,7 @@ It takes continuous effort to maintain and evolve processes in response to chall
 
 ### Control technical debt
 
-Technical debt is a term which refers to things about the way a system is built which are not apparent to users of the system, but impact the ability of the team to make changes to it quickly and safely. Tech debt arises due to processes or practices in the past, but has an ongoing impact on the present.
-
-Technical debt:
-*	Leads to bugs and loss of reliability.
-*	Means changes take longer.
-*	Makes it harder to predict how long any given change will take.
-*	Causes dissatisfaction and disengagement in the team.
+[Technical debt](tech-debt.md) is a term which refers to things about the way a system is built which are not apparent to users of the system, but impact the ability of the team to make changes to it quickly and safely.
 
 Without sustained improvement effort these all get worse over time, reducing capacity to deliver features. If little or no tech debt improvement work is done, delivery may initially be faster but over time it becomes progressively slower and less predictable.
 

tech-debt.md

@@ -0,0 +1,69 @@
+# Technical debt
+
+## Context
+
+* This is part of a broader [quality framework](README.md)
+
+## Overview
+
+"Technical debt" is a term which refers to undesirable things about the way a system is built which are not apparent to users of the system, but impact the ability of the team to make changes to it quickly and safely. Tech debt arises due to processes or practices in the past, but has an ongoing impact on the present, in that it:
+
+*	Leads to bugs and loss of reliability
+*	Means changes take longer to develop, and makes it harder to predict how long the work will take
+*	Causes dissatisfaction and disengagement in the delivery team
+
+There are many different views on what is and isn't tech debt - this is ours.
+
+## Purpose
+
+This definition is important because an understanding of technical debt supports teams to make prioritisation decisions such that systems will remain safe.
+
+Teams must record technical debt in their backlog, and they must actively manage the risks associated with that debt.
+
+## Definition
+
+We define tech debt as: the negative results of design & implementation decisions, and how those decisions age over time if they aren’t incrementally adjusted or improved
+
+* This includes technical decisions that are made for short-term benefit (e.g. delivery time or cost) that will slow you down or increase your costs / risks over time
+* This also includes technical decisions that were appropriate at the time, but better options exist now (e.g. new technologies that weren't available at the time)
+
+Note: it includes working practices as well as the software: the scope includes anything that's not in line with the contents of this [quality framework](README.md)
+
+### Examples of what it IS
+
+Here is a non-exhaustive list of examples we consider to be *in* scope of "technical debt":
+
+* Unknown / poor code hygiene and lack of coding standards
+* Unknown / poor [resilience test-automation](practices/service-reliability.md)
+* Unknown / poor [security test-automation](practices/security.md)
+* Unknown / poor accessibility test-automation
+* Use of technologies not endorsed by the organisation
+* Code you no longer need ([e.g. a new managed service is available](patterns/outsource-bottom-up.md))
+* Technologies no longer needed (e.g. you've introduced something better than what you used before)
+* CI issues, e.g. lack of [fast feedback](patterns/fast-feedback.md), or intermittent [build failures](practices/continuous-integration.md)
+* Manual processes that could be [automated](patterns/automate-everything.md)
+* Software components with inappropriate / confused [domain boundaries](patterns/architect-for-flow.md)
+* Use of obsolete / unsupported technologies
+* Self-run tooling where a [SaaS offering](patterns/outsource-bottom-up.md) exists, e.g. sonarqube vs sonarcloud
+
+### Examples of what it ISN'T
+
+Here is a non-exhaustive list of examples we consider to be *out of* scope of "technical debt":
+
+* "Architectural debt", for example:
+  * A business capability within a product that doesn't need to exist within that product, because a dedicated / strategic service is now available to perform the same function
+  * Use of no-longer-preferred architectural patterns, e.g. monolith pattern
+* "Functional debt", for example:
+  * Bugs
+  * New features that haven't been built yet
+* Operational issues within the delivery & operational teams, for example:
+  * Poor communication channels from/to end users, between operational teams, or within teams
+  * Silos of knowledge / single points of failure within the team
+  * Poorly understood team responsibilities
+  * Poorly aligned contracts / organisation-level-agreements across suppliers / teams
+
+## Instrumentation
+
+The collection of tech debt should be fully automated. Some aspects of the above "in scope" list are much easier to collect than others - many of the above are reflected in [metrics](insights/metrics.md).
+
+TO DO: further details around instrumentation