4 ms·

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:/

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/c7875704971be998a5399ce83e66a5dada03aad4 http://github.com/github/gollum/commit/c7875704971be998a5399...

mojombo 16y ago
You may also be interested to see how the Readme evolved over time as I implemented what I had specified. http://github.com/github/gollum/commits/master/README.md 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.
- mrpsbrk 16y ago
  Maybe it should shrink as you realize better and more concise ways to say the same thing ;-)
- sr3d 16y ago
  self-plug: http://sr3d.github.com/GithubFinder/?user_id=github&repo=gollum http://sr3d.github.com/GithubFinder/?user_id=github&repo... and click on README.md and you can diff to see how the README.md file changed overtime. A nice Readme is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of users better since it's a good and direct way to explain why this project matters, and why people should use and contribute to the project. Good readme should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating. Also, I watched a Google video of Brian Fitzpatrick and Ben Collins, who developed Subversion, on how to defend open source projects from "poisonous". Their number one rule is "When you launch a project, carefully define your mission - and post that mission to a conspicuous web page." (http://www.theregister.co.uk/2008/05/30/google_open_source_talk/ http://www.theregister.co.uk/2008/05/30/google_open_source_t...) A readme can serve as a mission statement to define a clear path of the project. If a project is like a book, the Readme file would be the cover with all the raves and hooks to get people to pick up the book. But as they say, "don't judge a book by its cover", "don't judge a project by its Readme file" either. But good readme will definitely help.

mojombo 16y ago

You may also be interested to see how the Readme evolved over time as I implemented what I had specified. http://github.com/github/gollum/commits/master/README.md 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.

mrpsbrk 16y ago
Maybe it should shrink as you realize better and more concise ways to say the same thing ;-)
sr3d 16y ago
self-plug: http://sr3d.github.com/GithubFinder/?user_id=github&repo=gollum http://sr3d.github.com/GithubFinder/?user_id=github&repo... and click on README.md and you can diff to see how the README.md file changed overtime. A nice Readme is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of users better since it's a good and direct way to explain why this project matters, and why people should use and contribute to the project. Good readme should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating. Also, I watched a Google video of Brian Fitzpatrick and Ben Collins, who developed Subversion, on how to defend open source projects from "poisonous". Their number one rule is "When you launch a project, carefully define your mission - and post that mission to a conspicuous web page." (http://www.theregister.co.uk/2008/05/30/google_open_source_talk/ http://www.theregister.co.uk/2008/05/30/google_open_source_t...) A readme can serve as a mission statement to define a clear path of the project. If a project is like a book, the Readme file would be the cover with all the raves and hooks to get people to pick up the book. But as they say, "don't judge a book by its cover", "don't judge a project by its Readme file" either. But good readme will definitely help.