Designing effective strategies for both testing and documentation of a codebase is hard.
It’s hard because the problem exists at multiple levels at once. There are immediate, mechanical challenges: it’s hard simply to write a single passing test that verifies desired behaviour, or a document that conveys a clear understanding. But every local decision sets a precedent which also affects the system as a whole. Each test and each doc communicates something about the entire strategy.
If all instances were written this way, would the system still function as intended? If everything were a unit test, would we miss failures that only emerge end-to-end? If documentation for every feature went into this level of detail, would we end up with so much content that understanding the system becomes harder, not easier?
These local choices compound into system-level effects. They shape how people behave, what they prioritise, and how quality changes over time. The cumulative effect of many small decisions determines not just maintainability, but the ultimate purpose of the system.
Meanwhile, at a higher level, an explicit strategy is needed—along with a simple narrative that builds common understanding. That narrative must be precise enough to guide individual decisions, yet simple enough to communicate beyond the development team. Stakeholders need a mental model allowing them to effectively prioritise developer capacity. Existing frameworks for this narrative, such as the testing pyramid, often sacrifice this nuance for accessibility—this helps their adoption, but loses useful precision, which leaves much of the real decision-making to the expertise and discretion of the individual contributor.
Testing and documentation are systems: a collection of interdependent components that interact to produce some result and can contain self-regulating or destructive feedback loops.
By examining both through the lens of Systems Thinking, we can examine and address the common causes of the failure modes to which each is susceptible.
Each software project has a Testing System and Documentation System which depends on its unique conditions. Even if a codebase has no tests or documentation, there is still an underlying mental model and system which has resulted in this outcome; the system can still exist even if it regulates the amount of tests and documentation to zero.
As the conditions for each software project are different, I will examine the components commonly found in both systems; bear in mind that the systems of your project may vary and you could map out their components more precisely.
In systems thinking, the important types of components are the: