Readme Driven Development

tom.preston-werner.com

69 points·shawndumas··9 comments

This article looks like it has some good ideas in it. But the practical side of me thinks it would probably only work well in the context of small- to medium-sized projects whose users include few, if any, technically ignorant people (libraries, command-line tools, etc.).

Maybe (?).

Also, this has been submitted & discussed before:

http://news.ycombinator.com/item?id=1627246

This is a circuitious restatement of Fred Brooks' technique of writing the documentation first and having that be the framework from which the features of the code progress, such that usable code is a foregone conclusion if there is nothing in the software that is missing from the documentation. Transposed from mainframe manuals to README files, natch.

The difference, according to the article, is that the README should not be too detailed, so as to prevent the process from turning into a waterfall model by another name.

It's a distinction without a difference when that distinction is merely to include less detail. I don't consider doc-driven implementation to imply waterfall, though. It's just as close to BDD.

That's great: I'd love to see more "enterprise" software written this way.

But isn't this just a plea for a small design document up front? Not a fluffy mountain of "Word" format piffle, but some plain language explanations.

Am I the only one who's been jaded by all those Buzzword-driven "methodologies"? If anything, its development-driven-development. Anything else is practices.

I'd say we should take this a step further, and substitute value (specifically business value) for README.

This is the approach taken by agile methodologies.

This is from Aug/2010.

Reply on news.ycombinator.com