Create a gist now

Instantly share code, notes, and snippets.

@zsup /ddd.md
Last active May 15, 2018

What would you like to do?
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

This comment has been minimized.

Show comment Hide comment
@zlosch

zlosch 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?

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

This comment has been minimized.

Show comment Hide comment
@ebahsini

ebahsini Dec 11, 2016

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 ^

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

This comment has been minimized.

Show comment Hide comment
@thaichat04

thaichat04 Mar 29, 2017

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

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

@ssmusoke

This comment has been minimized.

Show comment Hide comment
@ssmusoke

ssmusoke Mar 30, 2017

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

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

@andres-lowrie

This comment has been minimized.

Show comment Hide comment
@andres-lowrie

andres-lowrie Apr 13, 2017

agree @ssmusoke; you should make this a repo

agree @ssmusoke; you should make this a repo

@ghost

This comment has been minimized.

Show comment Hide comment
@ghost

ghost Apr 17, 2017

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

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

This comment has been minimized.

Show comment Hide comment
@mikosullivan-dev

mikosullivan-dev Jun 14, 2017

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

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

This comment has been minimized.

Show comment Hide comment
@iandrosov

iandrosov Mar 5, 2018

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.

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.

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