Paul Osman’s socio-technical view of software explains why every system ever built is in a messy state that is difficult to navigate. It happens earlier to some projects and later to others — but it does happen eventually.
The systems we are building and operating are constantly being modified by different people, with different contexts, at different times, who may or may not speak to each other directly.
The longer a system lives the harder it gets to understand why a software is built and behaves in a certain way.
If you want to understand why your systems perform the way they do, it’s necessary to know how expertise is created and distributed amongst the people in your organization. The single best way to do this is to invest in incident analysis.
Incidents are only one reason software changes. Others include technological advancements, change in user behaviour, erratic product decisions, even personal preference of developers. These drivers will never be captured by incident write-ups alone. Constant documentation is required, outlining the context, reasoning and consequences of a decision. Ideally we can trace when a decision changes previous decision. In other words, use Architecture Decision Records to document changing software systems and to build a written history of decisions that you refer to long after people involved in those decisions have left.