如何编写开源项目的 README 文档

分享发现 · coding · Created at · Last by mm0089 Replied at · 2333 hits
2231

图片

运营一个开源项目就像在运营着一家 Startup,你期待更多人来使用你的项目,并给你的项目加 Star/提交 PR,但好的项目除了其自身真正契合了开发者的需求外,还需要一个好的 README。

有好的 README 文档的项目不一定是一个好开源项目,但一个好开源项目一定有一个好的 README。

目前 README 文档编写并没有规范,但一个友好的 README 是有其特征的,我们来看看一个好的 README 的必备要素。

国际化问题

首先要注意的是国际化问题,如果你希望自己的项目能获得更多人的使用,提供中英两种 README 文档是非常赞的。你可以在项目头部注明它。如 Coding 的 WebIDE 项目:

图片

项目名及简介

好的项目名及简介是好项目必不可少的。开源项目名不宜过长(除非你有特别的理由这么做),如果你不知道如何给自己的项目起名,可以使用 随机项目名产生器(适用于 Javascript 项目);项目简介可以是简单的几句话,但项目简介要说明几个你的开源项目用户想迫切了解的问题,这包括:

  • 这个开源项目是做什么的?
  • 这个项目是什么语言编写的?
  • 项目维护、CI、依赖更新状态(如果有的话,这也可以用)
  • 项目可用版本及其他版本
  • Demo 或官网地址(如果有)

如 Coding 的 WebIDE 项目:

图片

此外你还可以给项目增加一些图标以提高可读性,推荐使用 Shields.io

图片

你还可以将项目 Logo(如果有的话)放置在 REAME 顶部(这里推荐一个在线制作 Logo 的网站 Canva ),项目截图(Gif 动图更佳)也可以帮助你的用户更快速更直观地了解你的开源项目。

图片

功能

你可以注明这个项目的功能特点,亮点特色会大大提高访客使用这个项目的概率。

如 Coding 的 WebIDE 项目。

图片

用法

这是 README 中最重要的部分,你需要说明这个项目如何使用,这包括:

  • 如何下载这个项目:一般情况下 git clone 该项目地址即可,当然你也可以提供其他包管理下载安装方式;
  • 项目依赖:你需要说明编译运行这个项目前需要哪些依赖;
  • 安装:你需要说明如何编译安装/运行这个项目;
  • 部署:如果这个项目可以部署的话,请最好注明部署要注意的事项;
  • Debug 方法:理想状况下,你的用户会顺利编译并运行这个项目,但你要确保用户遇到了问题不会来打扰你(如提交 Issues),你还需要提供用户可能会遇到的常见问题;

图片

贡献

对于一个开源项目来说,令其作者最开心的莫过于有人提交 Pull Request 了。加入一个 CONTRIBUTING 文档将大大提高他人贡献你的项目的概率。

你可以说明你的代码规范,项目架构,如何测试和提交 Pull Request 的正确格式,以及其他有利于开发者进行贡献的信息,这将会使你的项目变得更加的规整如一。你可以在项目根目录新建一个 CONTRIBUTING 进行详细的说明并在 README 中添加其文件锚链接。如 Google 的 Template

图片

版权

版权是非常重要的,如果没有声明版权,很多用户特别是企业级用户将受制于法律问题,无法使用你的项目。关于如何选择开源项目许可证,推荐阅读这篇文章:《如何选择开源许可证?》

如 Coding 开源的 帮助文档 版权:

图片

鸣谢

你还可以感谢直接或间接为这个项目做出贡献的人、项目。

ttyd 项目:

图片

其他

我们推荐使用 Markdown 编写你的 README,请最好注意排版问题以增加文档可读性,推荐阅读 Coding 的 《文案排版规范》

图片

这就是一个好的 README 所需元素了,当然你还可以增加其他任何利于开发者的信息如 Roadmap 等等,这因项目而异。现在,去完善你的开源项目信息或开始做一个开源项目吧!

一些建议:选择一个好的代码托管平台/社区可以让你的开源项目获得更多曝光,你可以在 Coding 的 冒泡社区(可以理解为程序员的朋友圈)发布你的项目简介,截图和地址,与 30 万中国开发者分享你的开源项目;另外我们推荐同时 push 项目到 Coding 和 GitHub(可参考 该回答 ),得益于 Coding 遍布全国的 CDN,国内用户 clone 你的项目时的速度将大大提升。

Happy Coding ; )

(完)

你可能会感兴趣的文章:

本帖已被设为精华帖!
共收到 1 条回复
96
mm0089 · #1 ·

臺灣約妹找妓女做愛打炮賴mm0089 堅持讓你花得值得 讓你一次就滿意
薇薇外送茶優質正妹網站:http://www.kiss69lg.com/forum.php?forumlist=1&mobile=2
堅持讓你花得值得 讓你一次就滿意
保證咩咩 熟練多變的技巧 讓你三度回味
堅持誠信經營 絕不會說的天花亂墬 浪費彼此寶貴的時間
精心安排 保證約好的時間 20分鐘內火速到達
絕無強迫消費‧購買點數‧匯款‧ATM轉帳‧都是見到本人 滿意在消費
優咩咩都是經過篩選 絕無地雷 請放心光臨體驗享受
㊣平價錢又安心 熟客 新客都享有優惠
薇薇茶坊營業時間:中午12點-凌晨四點

外送地區:臺北新北林口龜山新竹臺中彰化南投高雄臺南
妹妹類型:學生 OL 巨乳 蘿莉 人妻 技術茶 空姐小模 AV女優 婚紗助理等
服務內容:全套服務
約妹流程:賴上先預約然後準時給房號在房間等妹到
約會地點:你自己選擇的旅館or熟客可送住家
消費方式:看到妹喜歡在當場現金交易 不喜歡可換三次

北部:一節6000內立減500送1000優惠券
一節7000 -8000第二節半價 買三節送一節
一節9000-10000 立減1000-2000送2次半價
一節11000-15000 立減3000-5000送3次半價
一節15000-30000 立減5000-8000 送一年半價

中南部:一節4000-5000 二節半價
一節6000-7000 買兩節送一節
一節7000-10000 買兩節送兩節
一節11000-15000 立減3000-5000送2次半價
一節15000-30000立減5000-8000送一年半價
約小姐部落格看照網址:https://www.cssanyu.org/bbs2/forum.php?mod=viewthread&tid=333726&extra=
約小姐部落格看照https://www.photostore.me/mm0089/?list=images&sort=date_desc&page=4&seek=ursjV
雙北桃園林口龜山新竹看照約妹網址:http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=143
臺中彰化南投看照約妹網址:http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=145
高雄臺南看照約妹網址:http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=147
安全旅館便宜經濟實惠旅館推薦:http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=182
色情圖片露點照片網址:http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=177
成人小說網址http://www.kiss69lg.com/forum.php?mod=forumdisplay&fid=163
台中台北外送茶莊、茶坊推薦|優質台北、高雄外約茶妹任你選南投外送茶/全套叫小姐彰化外送茶
草屯外送茶大台中外送茶,外約美女,薇薇外送茶賴mm0089外約服務網,台中一夜情 .台灣出差旅館叫小姐line:mm0089
台北外送茶/台中外送茶/高雄外送茶/台南外送茶/新竹外送茶/彰化外送茶/南投外送茶/薇薇外送茶賴mm0089大台灣台北台中高雄台南新竹地區喝茶服務外送茶薇薇外送茶賴mm0089/鼓山區看照約妹薇薇外送茶賴mm0089前鎮區美腿茶/三民區火辣茶/新興區惹火嫵媚茶/左營區MT外送... 外送/台北清涼茶莊/更多優質妹妹/台北外送茶莊/高雄外送茶/新竹外送茶/洗澡/愛愛薇薇外送茶賴mm0089/口交旅館酒店外送小姐/上門服務/薇薇外送茶賴mm0089茶魚分享/大台北外送茶坊/大台中外送茶坊/高雄外送茶/援交妹網站台灣叫小姐俱樂部,薇薇外送茶賴mm0089台北叫小姐,薇薇外送茶賴mm0089西門町外送服務 板橋外送茶高雄約妹外約茶莊薇薇外送茶賴mm0089/夜市附近叫小姐,85大樓叫小姐 高雄叫小姐按摩外送茶西?町找小姐薇薇外送茶賴mm0089林森北找茶喝/台北?正妹/台?援交找薇薇外送茶賴mm0089台北叫小姐台中旅館叫小姐高雄旅遊找妹兼職美女茶外送看照約妹好茶外送到家西?町找小姐|林森北找茶喝/台北?正妹/台?援交找薇薇外送茶賴mm0089
#台灣汽車旅館找小姐 #商旅找小姐薇薇外送茶賴mm0089 #星級酒店找小姐
#旅館找小姐 #商旅找小姐薇薇外送茶賴mm0089 #星級酒店找小姐 #旅館找小姐
#飯店找小姐 #住家找小姐薇薇外送茶賴mm0089 #賓館找小姐 #台灣出差旅遊外約 #台灣出差旅遊找小姐
#酒店外約叫茶 #台灣汽車旅館外約叫茶 薇薇外送茶賴mm0089#商旅外約叫茶 #星級酒店外約叫茶 #旅館外約叫茶 #飯店外約叫茶
#住家外約叫茶 #賓館外約叫茶 #台灣出差旅遊外約叫茶 薇薇外送茶賴mm0089#台灣出差旅遊外約叫茶 +薇薇外送茶賴mm0089#
台中外送茶 #台北外送茶 #新竹外送茶薇薇外送茶賴mm0089 #高雄外送茶 #台南外送茶 #彰化外送茶 #南投外送茶 #台中外約
#台北外約 #高雄外約薇薇外送茶賴mm0089 #新竹外約 #台南外約 #彰化外約 #南投外約 #台灣外送茶 #外送茶 #情愛全台外送茶看照約妹叫小姐
#外送茶不戴套 +薇薇外送茶賴mm0089#板橋外約 #三重外約 #永和外約 #中和外約 #汐止外約 #新莊外約 #土城外約
#新店外約 #蘆洲外約 #五股外約 #泰山外約 #淡水外約薇薇外送茶賴mm0089 #八里外約 #林口外約 #龜山外約 #台中外約 #高雄外約
#台北外約薇薇外送茶賴mm0089 #本土外約 #外約台妹 #中正外約 #大同外約 #松山外約+薇薇外送茶賴mm0089 #板橋外送茶 #板橋外約
#大安外約 #萬華外約 #信義外約薇薇外送茶賴mm0089 #士林外約 #北投外約 #內湖外約 #南港外約 #文山外約 #新竹外約 #台南外約
#西屯外約 #南屯外約 薇薇外送茶賴mm0089#北屯外約 #逢甲外約 #大里外約 #大雅外約 #七其外約 #東海外約 #烏日外約 #太平外約
#豐原外約薇薇外送茶賴mm0089 #沙鹿外約 薇薇外送茶賴mm0089#逢甲茶莊 #逢甲全套
#薇薇外送茶賴mm0089逢甲外約 #逢甲外送茶 #逢甲叫小姐 #逢甲打砲 屏東汽車旅館叫小姐.薇薇外送茶賴mm0089屏東找茶,屏東外送舒壓按摩.屏東護膚全套外約.屏東找妹薇薇外送茶賴mm0089.屏東找小姐.屏東汽車旅館叫妹妹服務薇薇外送茶賴mm0089.屏東叫小姐.妹妹服務找歡樂.薇薇外送茶賴mm0089屏東優質外送茶莊.屏東出差旅遊約妹 .薇薇外送茶賴mm0089屏東正妹論壇.屏東約情人.薇薇外送茶賴mm0089屏東找女人兼職妹.推薦屏東茶莊##屏東外約妹妹價位#屏東找小姐.薇薇外送茶賴mm0089屏東全套外送.屏東辣妹薇薇外送茶賴mm0089.屏東找學生妹.人妻
#逢甲茶訊 #逢甲援交 #逢甲找女人薇薇外送茶賴mm0089 #逢甲魚訊 #逢甲炮神器 #逢甲紓壓 #逢甲性愛服務 #逢甲鐘點情人 #
太平全套 #薇薇外送茶賴mm0089大里全套 #沙鹿全套 #豐原全套 #大雅全套 #烏日全套薇薇外送茶賴mm0089 #台中車站應召 #台中南屯約妹
#台中西屯叫小姐 #台中逢甲外送 #台中勤美約妹薇薇外送茶賴mm0089 #台中車站叫小姐 #台中北屯應召 #台中南屯叫雞 #台中車站叫妹
#台中北區叫小姐薇薇外送茶賴mm0089 #台中應召 #台中車站叫雞 #台中車站茶莊 #台中西屯外送薇薇外送茶賴mm0089 #台中逢甲約砲 #台中北屯叫妹 #台中市區應召桃園半套店薇薇外送茶賴mm0089 ,#桃園半套價錢 #桃園找援,#桃園聯天室找援,#桃園西門找援桃園半套店薇薇外送茶賴mm0089 ,#桃園半套價錢 台中一夜情,台中??,台中全套基隆叫小姐電話 #基隆叫小姐 #基隆飯店叫小姐 #基隆旅館叫小姐薇薇外送茶賴mm0089 #基隆找女人 #基隆找妹 #基隆出差叫小姐 #基隆打炮薇薇外送茶賴mm0089 #基隆看照約妹#桃園茶莊心得,#桃園茶莊ptt,#桃園桑拿薇薇外送茶賴mm0089 ,#桃園桑拿浴,#桃園桑拿網
#桃園桑拿論壇薇薇外送茶賴mm0089 ,#桃園桑拿澳門,#桃園桑拿168,#桃園半套店薇薇外送茶賴mm0089 ,#桃園半套價錢
台北外送茶/高雄鐘點情人外約,台北旅館叫小姐,台北鐘點情人,台灣一夜情,高雄一夜情,台中一夜情,台北一夜情,台北美女外約,台中美女外約,高雄美女外約,高雄茶莊,台中茶莊,台北茶莊,台北叫小姐,台中叫小姐,高雄叫小姐,高雄外約/外約/援交妹,吃魚喝茶論壇,大家來找茶,PLUS,伊利,微克成人網/女優GoGoGo/淘A片/一刀未剪/免費成人影音薇薇外送茶賴mm0089 /交換網站/交友網站/性愛成人網/一葉晴成人貼片/成人極品情色站/癡漢線上免費A片/台灣明星淫片流出露比線上免費A片/伊莉成人論壇/◆免費線上A片◆/寶貝一夜情聊天室/免費A片頻道/無名成人網/成人網/台北情色聯盟/天天幹貼圖/洪爺色情網/台灣噴精成人網/十八小妹自拍美少女自拍貼圖老婆自拍貼圖/色色女孩情色總站/A圖情色交流/666人氣貼圖/插插穴排行/69Kiss電影排行/薇薇外送茶賴mm0089 彩虹頻道/后宮電影院/中文搜性網/酷站排行入口/上我人妻/成人龍虎豹/干爹情色排行/十七歲少女/台灣1歲/104寫真銀行/插插穴排行/熱酷美眉網/台灣性樂園/只有貼圖/波波美女網/交換連結eyny,玩美情人,男人幫,高雄女外約,高雄外送,高雄賓館叫小姐,高雄飯店叫小姐,高雄鐘點情人外約,台北旅館叫小姐,彰化外送茶,台灣兼職美女外送,薇薇外送茶賴mm0089 台北兼職美女外約,台中外送茶坊,高雄外送茶坊,台北外送茶坊陸妹價格,檳榔西施清涼秀,台功援學生兼差 msn,援交妹,24h 台北私兼,CLUB,台南指壓 3k,高雄酒店經紀,台中學生兼差msn,台北 夜店 舞廳 酒吧 制服便服,中年夫妻聯誼,高雄媛交,台南茶妹,台北指油壓留言板,情趣精品,大台南一夜情人外約\俱樂部,台北賓館叫小姐,高雄原味貼身衣物買賣,夢時代購物中心,台北推拿中醫,0204一夜崤◆隆f聊天室,熟女圖,討論區,台南喝茶的店哪好,網路購物,台中理容按摩,台南陪唱,台北下\午茶 blog,高雄 砲友,台中好茶討論區,高雄茶店news,高雄按摩個人工作室,旅遊,台南24h台南24h餐廳,台北茶訊交流msn,卡債,台中旅館外叫服務,台中 spa油壓男按摩小姐服務/漁會玩美情人遊戲成人論壇 台北吃魚喝茶留言板外送/台北一夜情重點情/台北旅館飯店找服務叫小姐/找女人全套服務加按摩指油壓成人夜遊魚訊交流論壇區/台北應召站/伊莉喝茶/第一手論壇/外約愛愛/外約電話/外約高檔茶到府服務/伊莉plus28/成人性愛慾茶園 性交易/正妹外送服務/找茶論壇薇薇外送茶賴mm0089 /找茶討論區/台灣外送GTO/台灣樂緣外送茶/兩性論妹板橋外送酒店 北投泡溫泉三溫暖趙小姐/援交妹網站論壇/FB交友網站/UT天室交友一夜情炮友/台北喝茶買三送一接多買多送純情動感兼職妹/華僑台北旅遊出差消伴遊找女人茶/薇薇外送茶賴mm0089 極品俱樂部嚴選絕色經典,第一手娛樂論壇/卡提諾/玩美情人/吃魚喝茶網 薇薇外送茶賴mm0089 伊漁網/Plus論壇/台灣樂緣/小女人論壇/台灣論壇/微風論壇/伊莉論壇/禁地論壇/維克斯論壇/捷克論/男人幫論壇/大眾論壇/竹北旅館飯店找女人按摩舒壓叫小姐3p服務 愛情公寓論壇 交友/ 愛情/戀愛/貓都論壇/賽斯論壇/104論壇/九州娛樂論壇/櫻雪論壇/2B級/台灣、送茶坊台北外送茶坊,台中外送茶,高雄外送茶,美女外約服務/台中/高雄/新竹/彰化/莊極品俱樂部嚴選絕色經典,成人性愛慾茶園,找茶討論區,催情藥,唯美貼圖,成人論壇,網絡報稅,線上遊戲,高檔平價好茶,淫照聊天是尋夢園美女外送,情趣用品八大行業指油壓全套,暑假打工,網站設計,中國合夥人,鋼鐵俠3,HTC,蝴蝶機,變裝遊戲,茶,motel,hotel,性感絲襪,A片下載,AV女優,第一手論壇,貓都,卡提諾,喝茶,完美情人,BJ論壇,小女人論壇,卡提諾論壇,台灣論壇三溫暖中陪酒ktv,台北全套護膚個人工作室,尋找台南援交auty 美容美體 SPA沙龍,台北外約茶棧,台中越南餐廳,台南應召站,台北外送 3k,高雄下午茶外,台中三溫暖全套,台南全套油壓泰國,台南半套店1600元,高雄推拿指壓,小姐,台北夜生活 pub,台北單身聯誼,兼差,台北交換伴侶,台北一夜情,高雄聊天網,高雄美女兼職,台南車站美食,8000mile,台北一夜情緣俱樂部,高雄應徵\酒店酒店上班,高雄成人視訊聊天室,台南兼職找利菁,高雄24h到府指油壓,女兼職,酒店兼職\,壽山,台南茶訊茶資薇薇外送茶賴mm0089 ,台南陪酒小姐,高雄絲襪美腿高跟鞋,夫妻聯誼部落格,薇薇外送茶賴mm0089 台南小野貓檳榔西施外送時被下藥拍照,自拍女老師,找台中援妹地點,台北大陸妹價格,檳榔西施清涼秀,台功援學生兼差 msn,援交妹,24h 台北私兼,CLUB,台南指壓 3k,高雄酒店經紀,台中學生兼差msn,台北 夜店 舞廳 酒吧 制服便服,中年夫妻聯誼,高雄媛交,台南茶妹,台北指油壓留言板,情趣精品,大台南一夜情人外約\俱樂部,台北賓館叫小姐,高雄原味貼身衣物買賣,夢時代購物中心,台北推拿中醫,0204一夜崤◆隆f聊天室,熟女圖,討論區,台南喝茶的店哪好,網福祿猴林千又 吳宗憲 2015 黑豹旗 王大陸 徐太宇 登革熱 波多野結衣 金鐘獎 蔡英文 洪秀柱 蛇精男 靈異 鬼故事 柯文哲 柯P 大家來說鬼 綜藝玩很大 時尚脈動 賈靜雯 陳佩琪 氣象 反課綱 2015星光大賞 宅男女神 愛爾麗 泛舟哥 張吉吟 ET看電影 八仙 塵爆 楊子晴 范冰冰 安心亞 陳泱瑾 Grace ISIS 林書豪

需要 Sign In 后方可回复, 如果你还没有账号请点击这里 Sign Up