SpecMD — What if Your Documentation Was Your Code?

The article discusses the idea of SpecMD, where documentation is written in Markdown and becomes the source of truth for how the software should behave. This approach aims to address the common issues of outdated, ignored, and inconsistent documentation.

Details

The article presents the problem of documentation often being out of sync with the actual code, which can lead to issues like outdated, ignored, and inconsistent information. The idea behind SpecMD is to write the intended behavior and rules in plain text Markdown, and have that Markdown become the source of truth for the software's implementation. This way, if the documentation and the code diverge, the test fails, and the inconsistency is immediately visible. The article highlights the benefits of this approach, such as every business rule in the documentation being automatically tested, documentation becoming a living part of software development, new developers learning behavior from Markdown instead of tribal knowledge, and changes to rules requiring changes to the documentation. The author suggests that SpecMD can be particularly helpful for teams building critical systems, managing large or distributed codebases, onboarding new developers often, maintaining complex business rules, and needing reliable documentation trust.