Documentation-Driven Development (DDD)

ddd.md

Documentation-Driven Development

The philosophy behind Documentation-Driven Development is a simple: from the perspective of a user, if a feature is not documented, then it doesn't exist, and if a feature is documented incorrectly, then it's broken.

• Document the feature first. Figure out how you're going to describe the feature to users; if it's not documented, it doesn't exist. Documentation is the best way to define a feature in a user's eyes.
• Whenever possible, documentation should be reviewed by users (community or Spark Elite) before any development begins.
• Once documentation has been written, development should commence, and test-driven development is preferred.
• Unit tests should be written that test the features as described by the documentation. If the functionality ever comes out of alignment with the documentation, tests should fail.
• When a feature is being modified, it should be modified documentation-first.
• When documentation is modified, so should be the tests.
• Documentation and software should both be versioned, and versions should match, so someone working with old versions of software should be able to find the proper documentation.

So, the preferred order of operations for new features:

• Write documentation
• Get feedback on documentation
• Test-driven development (where tests align with documentation)
• Push features to staging
• Functional testing on staging, as necessary
• Deliver feature
• Publish documentation
• Increment versions

I'm glad I've found this via charlax/professional-programming, sounds like a good system. Might delve deeper into this and talk to my boss.

Absolutely agree with this sentiment. I find a lot of places find documentation as a chore. And then when newer developers try to figure out the why and design behind why certain features work they way they do are confused and ask if there is any documentation.

And the response is usually some tribal knowledge passed through multiple devs or not really sure, its always been like this.

@WarrenWongCodes Indeed. Also, I think of Documentation-driven Development and Readme-driven Development as almost variants of Knuth's Literate Programming.

in that case, i propose Artificially Literate Programming -- tongue planted firmly in cheek -- wherein the discipline is precisely as Knuth described it, but one uses GPT models to assist the process.

https://diataxis.fr/

Document a concept before implementing it. If you take a break from development, you can always go back and refresh your memory by reading docs. Tests are secondary.

Do you have any reference about document generation tool supporting DDD ?

"document generation tool" = AI

This old discussion hits differently in the AI era!

For those who haven't experienced it, I want to share some context document files that can be fed to AI coding agents like Claude Code, Cursor, etc:

• PLAN.md - current project roadmap and objectives
• ARCHITECTURE.md - technical decisions and system design
• TODO.md - current tasks and their status
• DECISIONS.md - decision history with rationale
• COLLABORATION.md - handoff notes from other tools
Source : https://news.ycombinator.com/item?id=44833651

These files help AI understand not just what the code does, but why certain choices were made and what the project goals are.

What is Spark Elite please?

I have asked myself what Spark Elite could mean. Probably everyone has already find out the answer. But for the ones who not, I asked Google Gemini providing him the context of this Gist and got this answer. Which to me sounds plausible:

_In the context of that document, "Spark Elite" refers to a select group of advanced users or experts—likely an internal team or a highly qualified community segment—who possess the technical insight needed to validate whether documentation is accurate and useful before development starts.

While the term seems specific to the author's particular project or workplace, its role within the Documentation-Driven Development (DDD) methodology is to serve as a quality gate.

Essentially, the author is stating that documentation should be vetted by those who understand the product best (the broader community or this "Elite" group) to ensure that when coding begins, the requirements are crystal clear and free of misunderstandings._