Many years ago (at a different company) I was working on a cloud native connector service. The service would create uniform/canonical REST APIs to work with any system by abstracting the native interfaces provided by them. These abstractions were called connectors which was unique for each system we integrated with. To scale the connector development, we took (paid contract) help from external partners. Specifications with requirements were written (in English) and given to the partner for development.
When the connectors developed by the partner were ready and integrated into the rest of the service, invariably there were issues. It would take lot of back and forth and debugging to identify the source of the problem. The root cause almost always boiled down to one thing.
What we “meant” in the spec and what was “understood” from it was not always same.
At one point the Chief Architect got so annoyed that he said: “We need an executable spec. Period.” Instead of giving our requirement specification as a document in English, he wanted us to give it as a set of compliance tests that would be run on the finished artifact and accept if all tests passed. The developers in the partner organization has access to the tests so that could run it early on get to feedback. If this sounds like TDD and Contract Tests you are right.
This shifted the problem left for both of us. We spent more time upfront writing the spec as tests and the developers spent more time validating what they were doing upfront instead of waiting for the big-bang integration at the end. This mechanism solved many of the issues we had and the integration process started becoming less painful, more streamlined and predictable.
The paradigm shift to use executable spec made us focus on the real issue (communication gaps and wasted effort) instead of getting into blame game.
This approach is something which has helped me later in other projects and companies. For example when we wrote the REST API guidelines spec, what helped adoption was the validation tool - executable code/tests which would check for the different guidelines and give instant feedback with a pass/fail. I’m 100% sure that developers learned more about the guidelines working with the tests hands-on than they did reading the spec document (which is admittedly boring and soporific).
I have learned that similar to the adage: “What can not be measured can not be improved” there is one more when it comes to specs: “What can not be executed (as a test) will not be (easily) complied with.”
We have the (REST API guidelines) spec written in English and many parts of it are translated to an executable spec (mocha tests in our case). So both co-exist.
However I’m hoping that for one of the future projects we take it to the next level. We write only the executable spec. And there is an option in the executable spec to spit out the English for it as a markdown/PDF. Turn the tables around.