{
  "$type": "site.standard.document",
  "canonicalUrl": "https://deterministic.space/readme-driven-development.html",
  "path": "/readme-driven-development.html",
  "publishedAt": "2016-08-21T00:00:00.000Z",
  "site": "at://did:plc:x67qh7v3fd7znbdhauc45ng3/site.standard.publication/3mjcd2t6afe25",
  "textContent": "Like most other (\\w)DD techniques[^1], \"README-driven Development\" wants to guide your approach to software development. This approach works best for small, self-contained projects or libraries, whose API surface is no larger than what fits on a bunch of post-it notes. And of course for projects that you might not want to write _right now_ but just thought about in the shower that seemed like a good idea.\n\nThe premise is simple:\n\n> Before writing any code, write a README file that describes what your software should do.\n\n(I tend to call the file README.md and use Markdown syntax, but you can of course do whatever you want.)\n\nDescribe everything\n\nAside from the usual meta information like\n\n- a general description of the project,\n- the name of the authors,\n- links to other pages (e.g. generated API documentation),\n- the license this is published under,\n- and maybe the current build status,\n\nyour README file must contain a pretty precise description on how to use this software.\n\nThese questions might help:\n\n- What do you need to write to show how to use this?\n- What features do you need to show so a user (and the implementor!) understand what you were aiming for?\n- How do you _want_ your program/library to be used?\n\nThe brilliant thing is this: You don't describe the current state of an existing project, but the ideal state you would love to have.\n\nWith an example\n\nLet's say you want to write a library that can extract the most dominant colors from an image file[^2]: You need to show\n\n1. how to load the library,\n2. which functions/data structures the user can use,\n3. how to load an image,\n4. and then what kind of data you get back.\n\nImagine the most convenient API for this, and write it down.\n\nThat you want your software to do\n\nTreat your README as a test file—literally! Structure the (code) examples in a way that they can actually be run and will work (once you wrote the code).\n\nYou can use tools like skeptic to extract code blocks from Markdown files and run them as unit tests.\n\nAnd publish the README\n\nAfter you wrote the README file, you should publish it. Probably with a big \"THIS IS JUST AN IDEA SO FAR\" warning. Maybe just as a Gist, but definitely in a place where you (or others) can easily start implementing the features you described.\n\n- - -\n\nAfter posting this, Salty Rando informed me that Tom Preston-Werner already wrote about Readme Driven Development in 2010!\n\n[^1]: E.g., Test-driven Development, Behavior-driven Development, or Calendar-driven Development.\n[^2]: Been there, done that. (That README is pretty bad, though.)",
  "title": "README-driven Development",
  "updatedAt": "2016-08-21T00:00:00.000Z"
}