There is no “Right Answer”
In a Traditional Development Model – there is no single, authoritative description of what’s “right”. If there’s a specification at the beginning of the process, that is authoritative to start out with, but the moment the developers start writing code, the Spec becomes secondary. At the end of the day, if there is documentation, that hopefully says how the system actually works – but it’s not authoritative, stale and out of date, and frequently just wrong.
In a Traditional Development Model, the same notions/ideas are typically described again and again and again. Even if multiple languages/platforms are not supported, even a small project might easily have 3 or 4 “copies” of each concept.
- The Specification
- The Code
- The Tests
- The Documentation
Then, if a change is needed, the process repeats itself. First, a “Change Request” is created, then the code and unit tests are updated, and then, if there is time, the documentation might get updated as well.
Replication in “the Source Code”
Also, within “the code”, the same ideas are repeated over and over:
- Interfaces
- Data Classes
- APIs
- Persistence (DB/SQL/NoSql/Etc)
- Testing
- Helper Functions
- etc.
This is before you even get to systems which support/include multiple languages:
- Java/CSharp
- SQL
- JavaScript/TypeScript
- Json
- Python
- etc.
At the end of the day, it’s not uncommon for even small projects to include a description of what a “Customer” or “Widget” is, 10 or more times throughout the code.
Lots of different “Right Answers”
So in a traditional development model – there are typically 3 or 4 ways of doing each thing. The “database” does it one way, the API slightly differently, the front end differently still. In this model, there is no “right way” – just different ways.
Introducing a Single Source of Truth
With a single source of truth, (i.e. One, Single, Authoritative, Machine Readable, Description of the problem) things work very differently. Now, it’s easy to say if any code/documentation/test/api/etc is right or wrong. Simply compare it to the SSoT. If it matches, it’s right, if it doesn’t match it’s wrong – and should updated to match.
This is a really important benefit. It brings a clarity that is simply unmatchable in a “traditional” model.
Spec/Code/Docs – All for 1 and 1 for All
With an SSoT, the Specification is really a report, about a system that already exists. In other words, writing the specification involves first turning the SSoT into an English description of the technology at hand.
Being able to turn the SSoT into English is proof that the SSoT is sufficiently complete/sophisticated in it’s structure to accurately describe the technology. If we can turn it into English, we should be able to use different tools to turn it into any language on the planet.
And since both the English Words, and the Code, and the System “Documentation” at the end of the day are all derived from the same, Single Source of Truth, they will all match each other – Because They are Not Source Code. Instead, to start with, they are all derivative code. Each derived from the same source.
Now – when the SSoT changes, everything in the repository all changes, as set. The Specifications, the Code, The Tests, the Documentation, The APIs – All of “the plumbing”. It all gets updated, together.
Most of what you think of as Source Code is actually completely derivative.
