← Back to context

Comment by clemesha

16 years ago

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

3 comments

clemesha

Reply
mojombo  16 years 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

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.

  • sr3d  16 years ago

    self-plug: 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_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.

  • mrpsbrk  16 years ago

    Maybe it should shrink as you realize better and more concise ways to say the same thing ;-)