Readme Driven Development • Hacker News Board

Re: Readme Driven Development

#41

Post by silentbicycle » Mon, Aug 23, 2010, 10:42 PM UTC

tjpick wrote: post #34

Seems like we're just talking about writing a spec before the code, and README being a specific form/template/symbol for that. Starting to feel like we're moving full circle w.r.t. agile vs process/documentation heavy methodologies.

He mentioned in passing that writing a typical README requires just the right amount of planning upfront. It was tangential to his main point, about documentation, but I think it's a good observation.

It avoids both planning extremes: writing an incredibly detailed spec upfront without any feedback from prototyping (waterfall), and diving in without any planning and expecting tests to magically do your design for you (naive TDD).

It's good to having an articulate summary of your project, but for planning, the README is just a prop. It could just as well be "whiteboard-driven design" or whatever.

Re: Readme Driven Development

#42

Post by [deleted] » Mon, Aug 23, 2010, 10:56 PM UTC

c0ffeeadd1c7 wrote: post #28

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)

[deleted]

Re: Readme Driven Development

#43

Post by silentbicycle » Mon, Aug 23, 2010, 10:57 PM UTC

raggi wrote: post #29

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

Or even worse, when half the documentation is a screencast.

Re: Readme Driven Development

#44

Post by jacquesm » Mon, Aug 23, 2010, 10:58 PM UTC

[deleted] wrote: post #42

c0ffeeadd1c7 wrote: post #28

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)

[deleted]

That's a holdover from the good old days when you had to search through 3" of fanfold paper for your function, they become a bit easier to spot like that.

Re: Readme Driven Development

#45

Post by adorton » Mon, Aug 23, 2010, 11:25 PM UTC

benbjohnson wrote: post #31

I would love to see some way to relate test cases with sections of the README. That way you could see code coverage of your README. It's difficult to retroactively write a README after you've written your code but it can also be difficult to write all the code described by your README. The README shouldn't hold every detail of your implementation but it would be a good starting point for developers trying to find whe…

Docco (and its variants) do sort of what you describe:

http://jashkenas.github.com/docco/

I can see its usefulness in documenting test cases.

Re: Readme Driven Development

#46

Post by mojombo » Mon, Aug 23, 2010, 11:44 PM UTC

silentbicycle wrote: post #41

tjpick wrote: post #34

Seems like we're just talking about writing a spec before the code, and README being a specific form/template/symbol for that. Starting to feel like we're moving full circle w.r.t. agile vs process/documentation heavy methodologies.

He mentioned in passing that writing a typical README requires just the right amount of planning upfront. It was tangential to his main point, about documentation, but I think it's a good observation. It avoids both planning extremes: writing an incredibly detailed spec upfront without any feedback from prototyping (waterfall), and diving in without any planning and expecting tests to magically do your design for you…

The benefit of doing your design in a Readme over doing it on a whiteboard or elsewhere is that it becomes a nice piece of documentation sitting right there in the root of the project. The first place you look for an explanation of what the project does and how to use it. Everybody wins!

Re: Readme Driven Development

#47

Post by xiongchiamiov » Mon, Aug 23, 2010, 11:44 PM UTC

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.

That's a full third of my repos. :)

Re: Readme Driven Development

#48

Post by tjpick » Tue, Aug 24, 2010, 12:16 AM UTC

mojombo wrote: post #46

silentbicycle wrote: post #41

Earlier quoted context omitted.

He mentioned in passing that writing a typical README requires just the right amount of planning upfront. It was tangential to his main point, about documentation, but I think it's a good observation. It avoids both planning extremes: writing an incredibly detailed spec upfront without any feedback from prototyping (waterfall), and diving in without any planning and expecting tests to magically do your design for you…

The benefit of doing your design in a Readme over doing it on a whiteboard or elsewhere is that it becomes a nice piece of documentation sitting right there in the root of the project. The first place you look for an explanation of what the project does and how to use it. Everybody wins!

all true, but the fact that the advice boils down to "store your spec where people can easily read it later" must qualify for a Captain Obvious award.

Re: Readme Driven Development

#49

Post by sr3d » Tue, Aug 24, 2010, 12:20 AM UTC

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.

self-plug: http://sr3d.github.com/GithubFinder/?user_id=github&repo...

and click on README.md and you can diff to see how the README.md file changed overtime.

A nice Readme is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of users better since it's a good and direct way to explain why this project matters, and why people should use and contribute to the project. Good readme should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating.

Also, I watched a Google video of Brian Fitzpatrick and Ben Collins, who developed Subversion, on how to defend open source projects from "poisonous". Their number one rule is "When you launch a project, carefully define your mission - and post that mission to a conspicuous web page." (http://www.theregister.co.uk/2008/05/30/google_open_source_t...) A readme can serve as a mission statement to define a clear path of the project.

If a project is like a book, the Readme file would be the cover with all the raves and hooks to get people to pick up the book. But as they say, "don't judge a book by its cover", "don't judge a project by its Readme file" either. But good readme will definitely help.

Re: Readme Driven Development

#50

Post by silentbicycle » Tue, Aug 24, 2010, 2:46 AM UTC

mojombo wrote: post #46

silentbicycle wrote: post #41

Earlier quoted context omitted.

He mentioned in passing that writing a typical README requires just the right amount of planning upfront. It was tangential to his main point, about documentation, but I think it's a good observation. It avoids both planning extremes: writing an incredibly detailed spec upfront without any feedback from prototyping (waterfall), and diving in without any planning and expecting tests to magically do your design for you…

The benefit of doing your design in a Readme over doing it on a whiteboard or elsewhere is that it becomes a nice piece of documentation sitting right there in the root of the project. The first place you look for an explanation of what the project does and how to use it. Everybody wins!

Oh, I don't disagree with that part at all, I just think that your aside about it encouraging just the right amount of design upfront deserves more thought.

I tend to do design brainstorming on scratch paper, Emacs scratch buffers, and in Prolog, but I'm already convinced about the merits of having a good README, and would write one regardless. (Just like I write tests anyway, whether or not I do them upfront.)