Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Readme Driven Development

tom.preston-werner.com

Post reply on HN
Print view View original

21–30 of 59 posts

Re: Readme Driven Development

#21

Post by mojombo »

bjclark wrote: post #19
mojombo wrote: post #15

Earlier quoted context omitted.

All of those things are approaches to crafting better software. It is my observation that a lot of projects developed with these methodologies still lack proper documentation. And I see documentation, especially in the form of a good Readme, as critical to the design, usability, and longevity of a project.

Do you consider projects like http://erector.rubyforge.org/ , http://pivotal.github.com/jasmine/user-guide.html , or http://github.com/pivotal/cedar to have good documentation?

Sure. The documentation for those projects looks great!

Re: Readme Driven Development

#23

Post by integraleq »

this is an excellent post and quite relevant. i have found this kind of epiphany as well while writing a python based framework at my company. i would extend the README driven approach to even suggest a developer blog driven design methodology, since it allows for a more dynamic way to clarify points and also add diary entries for 'thinking aloud' while you are building complicated libraries.

Re: Readme Driven Development

#24

Post by silentbicycle »

So in a roundabout way, we're back to...design-driven design?

Writing a README early on (and figuring out your general project scope, etc.) is a good idea, sure. Fundamentally, though, it sounds like he's just saying that a Software Engineering Methodology(TM) is no replacement for common sense.

When people attempt to formalize (and, often, brand & market) common sense, it tends to substitute checklists for thought.

Re: Readme Driven Development

#25

Post by silentbicycle »

mbreese wrote: post #8
benatkin wrote: post #7

I have a hard time thinking seriously about this, because all I can think of right now are those repos on GitHub that have nothing but a README file.

They obviously haven't gotten to step two... writing the code.

sudo apt-get install readme-compiler

(declarative programming for the rest of us!)

Re: Readme Driven Development

#26

Post by mrpsbrk »

mojombo wrote: post #16
clemesha wrote: post #10

Seems that mojombo practices what he preaches. First commit by mojombo (from march 29, 2010) of Github's Gollum wiki reads "readme driven development!" http://github.com/github/gollum/commit/c7875704971be998a5399...

You may also be interested to see how the Readme evolved over time as I implemented what I had specified. http://github.com/github/gollum/commits/master/README.md Writing your Readme first doesn't mean you should never change it. It should grow and become even more refined, comprehensive, and accurate as you write the code.

Maybe it should shrink as you realize better and more concise ways to say the same thing ;-)

Re: Readme Driven Development

#27

Post by preston »

adamv wrote: post #5
vcr2 wrote: post #4

It would be nice, if we dont consider the fact that nobody reads README at all. "A perfect implementation of the wrong specification is worthless." The point of BDD is exactly this: bring specification to the scene, give it a first class citizen status, it becomes a live entity in the system, more influential than before. I don't believe Readme or any other document can be as influential as a Cucumber feature, for in…

From a "using stuff off of GitHub" perspective, the README file is front and center when you look at a project.

Yep. Especially when using GitHub regularly, I'd argue that the README is the most important documentation file of the entire repository.

Re: Readme Driven Development

#28

Post by c0ffeeadd1c7 »

next to a README there should be at least one line of documentation for every function longer then three lines of code.

I like documentation-driven design - when I'm to write a long and complex routine I always write in pseudo-code-comments what I am to do.

This pseudo code usually ends up as the documentation of the routine (little grammar/language update might be needed)

Re: Readme Driven Development

#29

Post by raggi »

integraleq wrote: post #23

this is an excellent post and quite relevant. i have found this kind of epiphany as well while writing a python based framework at my company. i would extend the README driven approach to even suggest a developer blog driven design methodology, since it allows for a more dynamic way to clarify points and also add diary entries for 'thinking aloud' while you are building complicated libraries.

no. blogs are not a substitute for documentation.

ruby has been suffering this for too long.

blogs have several problems:

- they don't get updated - they don't get patched - they don't ship with the software - they break when the user dies / moves / leaves / changes software - they have a lower signal to noise ratio

Re: Readme Driven Development

#30

Post by raggi »

vcr2 wrote: post #4

It would be nice, if we dont consider the fact that nobody reads README at all. "A perfect implementation of the wrong specification is worthless." The point of BDD is exactly this: bring specification to the scene, give it a first class citizen status, it becomes a live entity in the system, more influential than before. I don't believe Readme or any other document can be as influential as a Cucumber feature, for in…

show me a christian that grok'd the entire bible before calling themselves a christian, and i'll show you a developer who reads the entire behavioral specification of a library before using it.

your idea works for libraries that are small, it's appalling for libraries of any significant size.

the point of a readme is to provide a useful summary that is quick to start using for the critical path use cases.

if you look at a web framework in a language you don't know as an example, and try to find the introductory use cases in the tests, this should give you some idea of what you're suggesting.

Post reply on HN