11–20 of 59 posts
I'm completely lost as to how doing Extreme Programming means you don't have a good Readme for your Git-Powered wiki with sweet API?
There's no need for the README to excite me and make me want to dive deeper into the software if there are good blog posts about actual use cases. They would lead me to your repo where I could find out how to install it, what the dependencies are, what kind of things can be accomplished in just a few lines of code, and how to contribute.
But, as a developer, I don't necessarily start a new project with exactly those points in mind -- and why should I? Most of the time, I intuitively start somewhere in the middle and move up and down from there. It is only after some time that I recognize what this thing actually is that I'm building. From my point of view, that would be the appropriate time to write a README.
Serious question: What does TDD, BDD, Extreme Programming, SCRUM, Standups and all the stuff in the first paragraph have to do with writing a library or app with proper documentation? I'm completely lost as to how doing Extreme Programming means you don't have a good Readme for your Git-Powered wiki with sweet API?
Serious question: What does TDD, BDD, Extreme Programming, SCRUM, Standups and all the stuff in the first paragraph have to do with writing a library or app with proper documentation? I'm completely lost as to how doing Extreme Programming means you don't have a good Readme for your Git-Powered wiki with sweet API?
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...
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.
This should be followed by an overview of what should be in a readme, as well as examples of good and bad readmes. Still, good stuff. Just leaves a few questions.
A good readme is a lot like a good manpage: http://rtomayko.github.com/ronn/
A good README, on the other hand, explains why the accompanying program is useful, shows some examples of how to use it, and points the user towards detailed documentation.
Now, perhaps the _ideal_ man page would also serve as a perfectly good README. But if you do a survey of merely _good_ manpages, and use them as a standard for writing READMEs, then you're probably going to get mediocre READMEs. Typical Unix and Linux manpages, even the good ones, don't spend enough time on high-level overviews and examples.
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…
Serious question: What does TDD, BDD, Extreme Programming, SCRUM, Standups and all the stuff in the first paragraph have to do with writing a library or app with proper documentation? I'm completely lost as to how doing Extreme Programming means you don't have a good Readme for your Git-Powered wiki with sweet API?
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.
In the end the README didn't represent the status quo but instead became what we were aiming for. For the most part this succeeded, the main challenge I had was persuading my collaborator to actually review what i'd written.