As a long time moderator of Utopian, I have reviewed countless development projects submitted to the Utopian. One of the things that bother me on that reviews is the lack of READMEs about the projects.
Why README.md is an important file
README file is your starting point to get attention from other open-source contributors. Even though you put countless hours the real application code and created something astonishing, if you can't clearly explain the project, then nobody will see or contribute to your project.
I consider the README is the most important file in the open-source repositories. This is where you learn
- What the hell is that project?
- What problem does it solve?
- What are the limitations?
- What are the steps to use the project?
- What is the roadmap?
- How can you contribute?
That's a hell of an information in one file. Isn't it great? So, why do you even want to skip that file?
Readme Driven Development
Founder of Github posted an article about Readme Driven Development at 2010. Which has a headline of
Write your Readme first.
Writing READMEs before the actual code helps you in different angles.
- You design the application, first.
- You have a simple documentation.
- You can get feedback from co-workers, friends without actually doing anything. You can get feedback about internal APIs, naming, design choices on your project.
Good examples
Utopian compability
We have that policy regarding this topic..
The Github repository linked to the submission post must contain the project’s source code, a readme file with usage and install instructions and an appropriate open source license, or be directly connected to such a repository.
So, it's better to come up with great READMEs. :)