Skip to content

Instantly share code, notes, and snippets.

Last active July 17, 2024 03:47
Show Gist options
  • Save zsup/9434452 to your computer and use it in GitHub Desktop.
Save zsup/9434452 to your computer and use it in GitHub Desktop.
Documentation-Driven Development (DDD)

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
Copy link

dschinkel commented Jan 4, 2019

DDD is "Domain Driven Development" :P

Sorry to burst anyone's bubble here but: it's almost as if this "Documentation Driven Development" is some kind of chat people had 50 years ago, before BDD and ATDD came out. spoof spoiler

BDD and ATDD, this is nothing new. Don't use some new acronym that's unnecessary, we already have two and a ton of articles written about it and real world experience doing it in the past 20+ years already in our profession.

Check out - my site that lists companies who BDD/TDD

I also invite you to take part in our slack: where we talk about this stuff all the time. It's a very friendly group for beginners to Advanced TDD'ists, Agile Coaches, etc.

ATDD and BDD which is driving the implementation of code based off requirements, that start with business requirements (having conversations) in the form of stories or trello cards even is already and has been a thing for over 20 years and keeps improving every year that passes as more people come to practice it. Devs then take a story and Test Drive it using BDD Style tests or AKA "outside-in TDD". Those tests serve as:

  • design guidance
  • design feedback
  • automated living documentation that tells you at any given time the following:
    a) what business requirements are live and working and
    b) allow you to find out and discuss requirements with your stakeholders that may be stale or not quite right (we're human, conversations aren't always perfect, stories are not always perfect, customers change their mind)
  • stories or cards (should be super small always...always break them down to smaller than you think) tell a developer when they're "done" test driving the implementation
  • verification

ATDD by Example
GOOS (one of the most read books by TDD'ists globally who BDD)

Behavior-driven development
Introducing BDD

I currently BDD/TDD ReactJS in fact. Living documentation, starts with conversations, stories, then implementation via TDD.

@zlosch watch this, this is me in a hangout with JBrains and in it you can see an example of how to apply BDD style tests to a REST API. I've since then figured out an approach to writing backend tests in business lang.

When Requirements Change or Do Not Exist

When documentation is modified, so should be the tests


Stories or Cards are initial documentation as a result of communication**.
Acceptance tests are the Living documentation that prove the static documentation / initial requirements requested: Stories work
Adding more to a readme, adding how-tos, etc. simply means you're "adding extra static documentation" they shouldn't be the primary drivers or feedback mechanisms of code.

When a feature is being modified, it should be modified documentation-first

You do that with cards or stories. Not extensive documentation, readme files, etc.

Requirements can change due to:

  • customer changes their mind
  • team misunderstood the card or story when they thought they understood it together

When that happens you typically:

  • Create a new card for a new scope
  • Change course slightly in the way you're implementing the card you're already on. That could be no new card, a new card, up to you and how your team works
  • Delete any tests that are verifying old behavior that the customer no longer wants
  • Test drive the new behavior based on the new cards that signify changed requirements

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

Your tests which paint a story of requirements and written in business language are already scoped to the version of your codebase.

This has worked well for a long, long time in XP shops and being used more and more as the years pass by.

Note: you don't have to use Gherkin as a way to document features. It's nice but for example I write my acceptance tests in mocha or Jest without it.


Don't rely on rewriting a bunch of static docs when requirements aren't quit right or change as the sole driver of developing software.

Instead all you need todo is:

BDD (human side): Have conversations, write new stories or informal brief cards, whatever you want to call them and write them in whatever (literally a physical notecard, sticky, Jira Story, Trello Card...whatever)

then BDD (technical side): test drive that new behavior via BDD (BDD style tests driven by an outside-in TDD workflow). You start with higher level tests and end up with many more lower-level isolated tests. Do not rely on "mostly integration tests", stick to the "test pyramid" where more isolated tests give you a better safety net followed by a small set of integration tests on top of that.

Optional: then...if you want to tack on more static docs (add to your readme, tutorials, readmes, whatever) after that's fine. That's just called "lets add more static documentation"; it doesn't warrant a new acronym and shouldn't focus on static documentation as the sole means to verify stuff works, what's current, etc. Stories and then tests that implement those stories (living documentation) does that.

XP, Agile, ATDD, and BDD already do everything you are advocating here.

Copy link

Berkmann18 commented Jan 4, 2019

Great gist, and thankfully tools like ESLint are helpful when using DDD even if it doesn't involve TDD or BDD.
Alternatively, doing it in what some people on Twitter described as Readme DD could also be beneficial.

Copy link


Copy link

This needs some movement. Great concept and gist. Let’s get something spun up!

Copy link

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.

Copy link

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.

Copy link

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

Copy link

jons commented Feb 16, 2023

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.

Copy link

Copy link

hinell commented Nov 14, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment