Skip to content

Instantly share code, notes, and snippets.

@zsup
Last active March 14, 2024 01:17
Star You must be signed in to star a gist
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
@zlosch
Copy link

zlosch commented Oct 3, 2016

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.

We're doing this for REST APIs, which have a formal specification (RAML). We use it to generate the documentation and parse it in tests to verify the implementation. But how can it be done with purely textual documentation?

@ebahsini
Copy link

One version on the purely textual:

We give the repo/readme to a "non-technical" person, interns, or more junior level engineers and see if they can reproduce the desired effect, stand up the app, or break it. Probably not a great workflow but we have noticed that as sample size ^ the perception of documentation quality seems to ^

@thaichat04
Copy link

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

@ssmusoke
Copy link

Excellent - why don't you turn this into a repo that can be extended with more ideas ...

@andres-lowrie
Copy link

agree @ssmusoke; you should make this a repo

Copy link

ghost commented Apr 17, 2017

Personally, I find documentation driven development approach to work very well with LaTex on Git to support callaborative development.

@mikosullivan-dev
Copy link

mikosullivan-dev commented Jun 14, 2017

I'm really glad to see this idea is growing. I'm working on two projects through DDD: Testmin and Minvee.

@iandrosov
Copy link

This is an interesting topic. We are doing this type of TDD for Admins using combination of tools, Agile Accelerator - tracking all story requirements and test notes, examples, Acceptance criteria an discussions on feature/story, GitHub - source control for CI/CD and change management, Heroku App that integrates AA+SFDC Metadata+GitHub to run deployments during dev testing, Jenkins to push final feature to UAT or PROD. Admins have a test suite that changes every sprint to execute set of 150-200 tests to ensure new automation still work with old triggers etc.

@spaceghost69
Copy link

Hey there.

So we are doing a very much TDD framework called "Starter Ignite".

https://github.com/StarterInc/Ignite

Basic idea: Use Swagger/OpenAPI (REST api documentation specification) to generate/regenerate full stack React Native/Web apps based on JAM backend.

Feedback appreciated.

@dschinkel
Copy link

dschinkel commented Jan 4, 2019

DDD is "Domain Driven Development" :P

Sorry to burst anyone's bubble here but: https://twitter.com/DaveSchinkel/status/1080624137792614400 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 WeDoTDD.com - my site that lists companies who BDD/TDD

I also invite you to take part in our slack: slack.wedotdd.com 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

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

Articles
ATDD
Behavior-driven development
BDD IS LIKE TDD IF…
Introducing BDD
WHAT’S IN A STORY?

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

Look:

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

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.

@Berkmann18
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.

@chipper1
Copy link

1234

@jsonRUHLS
Copy link

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

@kobus1998
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.

@WarrenWongCodes
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.

@dschiavu
Copy link

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

@jons
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.

@ShalokShalom
Copy link

@hinell
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