When I'm researching new tools/libraries, the first thing I read is the README. If it's worthless, then it's a fair bet the tool/library is, as well, and I won't be using it by choice. After that, I look at the official documentation. If all it has is auto-generated API documentation, that's another strike against it. Then I look at the API documentation. The tests are somewhere way in the back after all of this.
From a "using stuff off of GitHub" perspective, the README file is front and center when you look at a project.
Yep. Especially when using GitHub regularly, I'd argue that the README is the most important documentation file of the entire repository.
The point is that writing one is valuable -- it tests your ability to articulate an understanding of your own work from a high level, which is not always obvious when our focus is frequently at the code level.
show me a christian that grok'd the entire bible before calling themselves a christian, and i'll show you a developer who reads the entire behavioral specification of a library before using it.
your idea works for libraries that are small, it's appalling for libraries of any significant size.
the point of a readme is to provide a useful summary that is quick to start using for the critical path use cases.
if you look at a web framework in a language you don't know as an example, and try to find the introductory use cases in the tests, this should give you some idea of what you're suggesting.
Re:Readme Driven Development
by stonemetal on Monday August 23, 2010 @04:09PM
(#1627877)
>>your idea works for libraries that are small, it's appalling for libraries of any significant size.
Really could you see a developer reading the entire .net or java standard library test suite before using either Java or C#
"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 instance.