Skip to content

Instantly share code, notes, and snippets.

@zsup
Last active February 23, 2024 19:03
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
@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