4 ms·

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 movin

by tjpick 16y 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.

joe_the_user 16y ago
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.
silentbicycle 16y ago
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.
- mojombo 16y ago
  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!
  - tjpick 16y ago
    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.
  - silentbicycle 16y ago
    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.)
- WorkerBee 16y ago
  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.

by tjpick 16y ago

joe_the_user 16y ago

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.

silentbicycle 16y ago

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.

mojombo 16y ago
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!
- tjpick 16y ago
  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.
- silentbicycle 16y ago
  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.)
WorkerBee 16y ago
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.