My repsonse to zsup/ddd.md in which he wrote:
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
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 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.
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.