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

51–59 of 59 posts

Re: Readme Driven Development

#51

Post by silentbicycle »

jacquesm wrote: post #44
[deleted] wrote: post #42

Earlier quoted context omitted.

[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.

Whoa sorry, I wouldn't have deleted the comment if I had seen your response. I had decided that I was just grumbling and it didn't add anything to the conversation.

More or less, I had said that I hate that kind of coding convention, because while it's well intentioned, in reality it mostly adds an incentive against extracting repetitive code out into new functions. Also, I'm tired of seeing comments that say:

    /*******************
     * theFunctionName *
     *******************/
because somebody's shortsighted coding conventions required it - they tend to camouflage comments that actually matter. If you need big headlines to find where your functions start, get a better editor. (But I'm sure that was less applicable a decade or two ago.)

Re: Readme Driven Development

#52

Post by benatkin »

xiongchiamiov wrote: post #47
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. :)

Sweet!

Reminds me of another gripe I have: Rails puts a README in the generated app directory. It's not worth it IMO. I wish they'd get rid of it or change the name, or failing that, GitHub would detect unmodified Rails READMEs and screen them out.

By the way, I think abandoned README-only repos are a side effect of something useful - attempting to start new projects on the right foot. I think starting projects like this probably does more good than harm, overall. :)

Re: Readme Driven Development

#53

Post by WorkerBee »

SCRUM ... all irrelevant unless the software we're building meets the needs of those that are using it.

That statement misses the entire point of Scrum. What are those short iterations for, if not to get feedback from those using the software? Why replan at the end of every sprint, if not to know how user needs have changed and been informed by the current software?

How is the readme so different from the sprint's user stories? Working from the desired end docs looks like another version of the currently fashionable "pull" methods. Not a bad one for a particular kind of project though.

Re: Readme Driven Development

#55

Post by WorkerBee »

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…

He mentioned in passing that writing a typical README requires just the right amount of planning upfront

"just the right amount of planning upfront" is exactly what Scrum should do. It's not full-circle at all, it's another approach to current good practices.

Re: Readme Driven Development

#56

Post by nadam »

Basically good advice, but it also depends on the project. Some projects are too experimental for this.

My approach is the following with my startup project (but not with my day-job project):

I start to write this: brainstorm.txt

In brainstorm.txt I don't have to be concrete and concise. I just write down all kind of ideas.

After a while I start to write this: design.txt This is very concrete (factual) and concise. It is not an essay, it is not written for other people. It is just for myself: to make a conceptual skeleton. It is not too structured, because it is impossible if it is about an innovative product. The only way I can avoid chaos is that I apply extreme minimalism. (Minimalist things are easier to structure, and don't need to be too structured.) Meanwhile I start to write code, mostly bottom-up. And I continuously refine design.txt.

The User's guide (I call the Readme User's Guide) is already a quite different story for me. It must be written for the user and not myself. I don't like fluffy user's guides, but still it should not be as concise and as abstract as my notes to myself. If I would have to start with the User's Guide than my brain would work in a 'user's guide writer mode'. For me 'engineer/hacker mode' is different.

Re: Readme Driven Development

#58

Post by benbjohnson »

adorton wrote: post #45
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.

That's awesome how it shows the comments and code side-by-side. The only downside is that I have to describe the functionality while I'm writing code instead of beforehand. Thanks, adorton.

Re: Readme Driven Development

#59

Post by integraleq »

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

You are correct. So I suppose I should alter my previous post by saying that it is a good way to go iff you are also willing to be diligent in your updates to keep the documentation as current as possible.
Post reply on HN