Some thoughts about READMEs in the context of open source projects:
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.
Some notes on the design: IMO { The navigation feels a little fragile, maybe because of the small font size and delicate lines. But it's also quite original, especially the "view by topic" branch. The right column (only visible on some pages) could easily be mistaken for advertising, possibly because of the tiny sans-serif type. Overall the style and copy gives a personal, likable impression. }
I especially like this idea: %q{The structure would also be used to harvest all the energy it produces according to Professor Ratti. "It would be a zero power cloud," he said.} #thumbsup
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.