SpecMD — What if Your Documentation Was Your Code?

Glauber Portella — Sat, 20 Dec 2025 20:48:09 +0000

One of the biggest pain points in software development is keeping documentation and code in sync.
We document later, when we have time, when we remember, when the project “stabilizes” — and then it never does.

But what if the flow was reversed?
What if the documentation was the code?

That’s the thinking behind SpecMD.

The Problem

Documentation is often:

outdated
ignored
inconsistent with the actual code
hard to maintain
rarely trusted

Meanwhile, the code is:

the source of truth
reliable
but rarely immediately understandable

These two worlds don’t have to be separate.

The Idea: SpecMD

SpecMD is an approach where documentation is written in Markdown, and that Markdown becomes the source of truth for how the software should behave.

The idea is simple:

Write the intended behavior and rules in plain text
That text becomes executable code
The code validates that the implementation matches the document

If documentation and implementation diverge:

The test fails
The inconsistency is visible immediately

Why It Matters

Imagine building software with these conditions:

✔️ Every business rule in the documentation is automatically tested
✔️ Docs become a living part of software development
✔️ New developers learn behavior from Markdown, not tribal knowledge
✔️ Changing a rule means changing the documentation
✔️ Documentation can’t drift, because it validates the actual code

That changes everything.

A Simple Example

A document line might say:

The user’s email address must be unique in the system.

That sentence becomes executable logic.

If the implementation allows duplicates, the document surfaces the error.

Documentation becomes enforcement.

Who Is This For?

SpecMD can help teams that:

build critical systems
manage large or distributed codebases
onboard new developers often
maintain complex business rules
need reliable documentation trust
want clarity and traceability

If you’ve suffered from stale documentation, this will resonate.

Read the Full Article

To dive deeper into the concept and see the bigger vision, here’s the full write-up:

https://medium.com/@glauberportella/specmd-what-if-your-documentation-was-your-code-81d8af1e97a6

GitHub Open Research Project at: https://github.com/glauberportella/specmd

Let’s Talk

What do you think?

Should documentation play a more active role in how we build software?

Can description become execution?

Drop your thoughts — I’d love to hear perspectives from other developers who’ve battled with this problem.

DEV Community: Glauber Portella