create account

Readme files, open-source projects, and Utopian by emrebeyler

View this thread on: hive.blog |  peakd.com |  ecency.com
open-source · @emrebeyler · (edited)
$10.19
Readme files, open-source projects, and Utopian
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](https://ipfs.busy.org/ipfs/QmRSVvNunc72SZPWy6dGCh5dGccjEQ23aVYMWmpVxegYz3)
<center><sup>A funny README for [vapor.js](https://github.com/madrobby/vapor.js) - 1k stars at Github.</sup></center>

#### Readme Driven Development
***

Founder of Github posted an [article](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) 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](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2) template for the open-source projects.

- A curated list of [projects](https://github.com/matiassingers/awesome-readme) having awesome READMEs.

### Utopian compability
***

We have that [policy regarding this topic.](https://join.utopian.io/guidelines/).

> 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. :)
👍  , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , and 280 others
👎  
properties (23)
authoremrebeyler
permlinkreadme-files-open-source-projects-and-utopian
categoryopen-source
json_metadata{"community":"busy","app":"steemit/0.1","format":"markdown","tags":["open-source","utopian-io","blog","readme","sndbox"],"links":["https://github.com/madrobby/vapor.js","http://tom.preston-werner.com/2010/08/23/readme-driven-development.html","https://gist.github.com/PurpleBooth/109311bb0361f32d87a2","https://github.com/matiassingers/awesome-readme","https://join.utopian.io/guidelines/"],"image":["https://ipfs.busy.org/ipfs/QmRSVvNunc72SZPWy6dGCh5dGccjEQ23aVYMWmpVxegYz3"]}
created2018-08-08 13:50:30
last_update2018-08-09 05:43:54
depth0
children9
last_payout2018-08-15 13:50:30
cashout_time1969-12-31 23:59:59
total_payout_value8.223 HBD
curator_payout_value1.971 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length2,358
author_reputation448,535,049,068,622
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,528,694
net_rshares7,251,127,080,553
author_curate_reward""
vote details (345)
@didic ·
$5.87
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](https://join.utopian.io/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](https://review.utopian.io/result/1/24444334).

---- 
Need help? Write a ticket on https://support.utopian.io/. 
Chat with us on [Discord](https://discord.gg/uTyJkNm). 
[[utopian-moderator]](https://join.utopian.io/)
👍  
properties (23)
authordidic
permlinkre-emrebeyler-readme-files-open-source-projects-and-utopian-20180810t182021256z
categoryopen-source
json_metadata{"tags":["open-source"],"links":["https://join.utopian.io/guidelines","https://review.utopian.io/result/1/24444334","https://support.utopian.io/","https://discord.gg/uTyJkNm","https://join.utopian.io/"],"app":"steemit/0.1"}
created2018-08-10 18:20:18
last_update2018-08-10 18:20:18
depth1
children2
last_payout2018-08-17 18:20:18
cashout_time1969-12-31 23:59:59
total_payout_value4.404 HBD
curator_payout_value1.467 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length825
author_reputation76,371,161,336,613
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,782,435
net_rshares4,563,772,108,317
author_curate_reward""
vote details (1)
@emrebeyler · 
No worries, didic. Thanks for your time reading it! :)
properties (22)
authoremrebeyler
permlinkre-didic-re-emrebeyler-readme-files-open-source-projects-and-utopian-20180810t183227795z
categoryopen-source
json_metadata{"tags":["open-source"],"app":"steemit/0.1"}
created2018-08-10 18:32:27
last_update2018-08-10 18:32:27
depth2
children0
last_payout2018-08-17 18:32:27
cashout_time1969-12-31 23:59:59
total_payout_value0.000 HBD
curator_payout_value0.000 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length54
author_reputation448,535,049,068,622
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,783,358
net_rshares0
@utopian-io · 
Thank you for your review, @didic!

So far this week you've reviewed 9 contributions. Keep up the good work!
properties (22)
authorutopian-io
permlinkre-re-emrebeyler-readme-files-open-source-projects-and-utopian-20180810t182021256z-20180814t130812z
categoryopen-source
json_metadata"{"app": "beem/0.19.42"}"
created2018-08-14 13:08:12
last_update2018-08-14 13:08:12
depth2
children0
last_payout2018-08-21 13:08:12
cashout_time1969-12-31 23:59:59
total_payout_value0.000 HBD
curator_payout_value0.000 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length108
author_reputation152,955,367,999,756
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id68,163,476
net_rshares0
@isnochys · 
Comment driven development
properties (22)
authorisnochys
permlinkre-emrebeyler-readme-files-open-source-projects-and-utopian-20180808t135847305z
categoryopen-source
json_metadata{"tags":["open-source"],"app":"steemit/0.1"}
created2018-08-08 13:58:48
last_update2018-08-08 13:58:48
depth1
children5
last_payout2018-08-15 13:58:48
cashout_time1969-12-31 23:59:59
total_payout_value0.000 HBD
curator_payout_value0.000 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length26
author_reputation48,442,901,208,172
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,529,399
net_rshares0
@emrebeyler · 
Code comments shouldn't be a thing.
properties (22)
authoremrebeyler
permlinkre-isnochys-re-emrebeyler-readme-files-open-source-projects-and-utopian-20180808t141142099z
categoryopen-source
json_metadata{"tags":["open-source"],"app":"steemit/0.1"}
created2018-08-08 14:11:42
last_update2018-08-08 14:11:42
depth2
children4
last_payout2018-08-15 14:11:42
cashout_time1969-12-31 23:59:59
total_payout_value0.000 HBD
curator_payout_value0.000 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length35
author_reputation448,535,049,068,622
root_title"Readme files, open-source projects, and Utopian"
beneficiaries[]
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,530,780
net_rshares0
@netuoso · 
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...

![](https://i.imgur.com/hGqsJ4X.png)
properties (22)
authornetuoso
permlinkre-emrebeyler-re-isnochys-re-emrebeyler-readme-files-open-source-projects-and-utopian-20180808t142058773z
categoryopen-source
json_metadata{"tags":["open-source"],"image":["https://i.imgur.com/hGqsJ4X.png"],"app":"steemit/0.1"}
created2018-08-08 14:20:57
last_update2018-08-08 14:20:57
depth3
children3
last_payout2018-08-15 14:20:57
cashout_time1969-12-31 23:59:59
total_payout_value0.000 HBD
curator_payout_value0.000 HBD
pending_payout_value0.000 HBD
promoted0.000 HBD
body_length186
author_reputation151,901,967,807,285
root_title"Readme files, open-source projects, and Utopian"
beneficiaries
0.
accountminnowsupport
weight500
max_accepted_payout1,000,000.000 HBD
percent_hbd10,000
post_id67,531,772
net_rshares0
Help/Feedback