SpecMD — What if Your Documentation Was Your Code?

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.