Comment by tjpick
16 years ago
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.
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.)
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.
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.
Well yeah...
You could pretty well describe the software methodologies of the last twenty years as being over-generalizations of basically good ideas. Once a given reasonable idea has pushed beyond its usefulness, the opposite good idea appears and ... is pushed beyond its usefulness.
Tossing out understanding and just having tests and code can easily result in disaster in many cases (compilers, sudoku solvers, etc) while over-designing can result in the opposite disaster in other cases.