Hacker Newsnew | comments | show | ask | jobs | submit | vcr2's comments login

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


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.


>>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#


Applications are open for YC Winter 2016

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact