Readme files, open-source projects, and Utopian

in #open-source6 years ago (edited)

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?
Screen Shot 2018-08-08 at 4.42.51 PM.png

A funny README for vapor.js - 1k stars at Github.

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


  • A README template for the open-source projects.

  • A curated list of projects having awesome READMEs.

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

Sort:  

While this post is certainly a useful reminder for people to use README files, one that is very much appreciated, it does not quite fit within the guidelines for the Utopian blog category in terms of length, detail, and relevance to any particular project. I'm still happy to see it, and hope folks take the message to heart, though!

Your contribution has been evaluated according to Utopian policies and guidelines, as well as a predefined set of questions pertaining to the category.

To view those questions and the relevant answers related to your post, click here.


Need help? Write a ticket on https://support.utopian.io/.
Chat with us on Discord.
[utopian-moderator]

No worries, didic. Thanks for your time reading it! :)

Thank you for your review, @didic!

So far this week you've reviewed 9 contributions. Keep up the good work!

Comment driven development

Code comments shouldn't be a thing.

Part of Utopian scores are based on code comments according to a breakdown I recently saw. Hopefully not much of the score is reflected from this...

I disagree with that question and suggested removing it since it leads unnnecessary comments on projects shared via Utopian.

Its weight is small on the score, though.

Edit: By saying "unnecessary comments", I mean that.

codecomments.png

If you have to comment your code you are probably not writing clear code.