若是你很着急、只是想要模板，能夠直接跳到底部（但這樣一點不酷），準備酷的人，邁出成爲README大師的第一步吧！（絕對不是點擊誘餌）
假如你剛剛建立了很棒的項目，並在GitHub上共享了它。你認爲如今你只需坐等世界告訴你這個項目有多酷。畢竟，在過去的一個月中，你爲這個極具挑戰性的項目付出了不懈的努力，對嗎？
好吧，讓咱們退後一步，從檢查項目的開發人員或用戶的角度來看。儘管你知道本身的項目有多酷，也知道它是如何解決一個（直到你出現以前）還沒有解決的緊迫問題，可是看你項目的人想知道你構建了一個什麼樣的世界。
若是人們不知道你的軟件是作什麼的，就不會使用它或爲它作出貢獻，而且極可能會在開源軟件的海洋中找到更清晰明瞭的東西。
好的README文檔就像是項目的外觀。這是一我的在你的項目中首先要看的東西，它提供了軟件的簡要介紹。
美觀實用的README文檔可使你的項目脫穎而出，並引發開發人員社區的關注。
這將幫助他們瞭解你的項目，以及它要如何使用、爲何他們應該作出貢獻。
「哇，夥計！太棒啦！既然你知道這麼多，爲何不告訴咱們該怎麼寫……」
嘿，我不能說有一套具體的規則，你要努力遵照這些規則，而不是要努力寫一個好的README。
我將分享我是如何爲個人開源項目寫README的，以及你在爲項目編寫README文件時應考慮的事項，這樣你將（有但願）收穫一些看法。
https://github.com/navendu-pottekkat
另外請記住，你不會一天以內就精通撰寫README。像全部事物同樣，它須要實踐。
我已經爲開源貢獻一段時間了，我注意到全部優秀的項目都有一個很棒的README。
當你位於項目界面時，你能夠幾分鐘以內啓動並運行你的項目版本。
有不少的貢獻者、拉取請求、頻繁發佈的更新版本，都有一個很棒的README。
新的開發人員將可以找到全部詳細信息以開始使用，例如安裝說明和貢獻指南。
新的用戶將可以經過詳細的屏幕截圖和演示學會如何使用該項目。
如下是個人NSFW過濾項目的README，我認爲這是我寫過最好的README：
https://github.com/navendu-pottekkat/nsfw-filter/blob/master/README.md
我將介紹README的不一樣部分，這些部分對於每一個README都是必不可少的。
下面是本例中使用的README文件的連接。你還能夠找到一個模板README，並直接複製和粘貼到項目中：
https://github.com/navendu-pottekkat/awesome-readme/tree/master
標題應具備自我解釋性，儘可能不要太拗口。
（固然存在例外，像本文「超棒的開源項目R
EADME編寫指南」會是一個很酷的名字）
爲你的README添加一個封面或橫幅圖片。爲何？由於它很容易引發人們的注意，並且看起來很酷。
等等，我忘了一件事。你能夠將此連接的README用做模板：
https://towardsdatascience.com/media/README-template.md
橫幅的最佳尺寸是1280x650px。你還能夠將其用於repo的社交預覽。
我我的使用Canva網站建立橫幅圖像。全部基本內容都是免費的（在大多數狀況下，你不須要專業版）。
看起來不錯吧？這些被稱爲徽章，它們經過提供一些快速看法提升了可讀性，對嗎？
你能夠在你的項目中使用無數徽章，並且它們確實取決於項目。下面是我在每一個項目中經常使用的一些。
我使用Shields IO網站製做徽章。這是一種簡單易用的工具，你可使用幾乎全部的徽章：
寫完項目後，最好對項目進行演示或預覽（視頻/ gif /屏幕截圖都是不錯的選擇），以便人們知道你的項目中會有什麼。你也能夠在上一節中的演示中添加產品說明。
在介紹了項目以後，添加目錄是一個好主意。這將令人們能夠更輕鬆地瀏覽你的README，並準確找到他們想要的內容。
這是一個示例目錄（哇！太酷了！），其實是本文的目錄。
你可能已經注意到了返回頂部的按鈕（若是沒有，請注意，它就在這裏！）。這是一個好主意，由於它使README更易於瀏覽。
第一個問題應該是如何安裝（如何使用項目或如何在機器中啓動編輯）。
這裏應該給用戶詳盡的想法，並說明他們如何使用項目repo的全部步驟。
個人方法是，完成README後，從頭開始閱讀這些步驟並檢查是否有效。
要使用此項目，請首先使用如下命令在你的設備上克隆repo：
https://github.com/navendu-pottekkat/nsfw-filter.git
這部分是可選的，用於向用戶提供安裝後如何使用項目的信息，也能夠添加到「安裝」部分。
你能夠深刻說明代碼如何工做及全部內容如何組合在一塊兒。
理想狀況下，你應該使README保持簡潔。若是須要添加更復雜的說明，請使用Wiki：
https://github.com/navendu-pottekkat/nsfw-filter/wiki
在這裏，你可讓人們知道他們如何爲你的項目作出貢獻。下面給出了一些方法。
你的項目備受青睞，而且已經被成千上萬的人使用（有了這個README文件，將會有更高使用量）。如今，是時候尋找人員或組織來贊助你的項目了。
這多是由於你沒有從項目中得到任何收入，你須要錢來維持項目生存。
你能夠在此部分中添加人們如何贊助你的項目。在此處添加你的patreon或GitHub贊助商連接，以方便訪問。
一個好主意是還要向贊助商展現他們的組織徽標或徽章，向他們表達你的愛！（總有一天我會找到贊助商，並向他們表達個人愛）
這是爲了讓人們瞭解如何在你的項目中提出問題或提出功能要求。
就我的和標準而言，你應該使用一個問題模板和拉取請求模板，以便用戶打開新問題時能夠按照項目指南輕鬆地格式化它：
https://github.com/navendu-pottekkat/nsfw-filter/blob/master/ISSUE_TEMPLATE.md
你還能夠添加聯繫人詳細信息，以便人們就你的項目與你取得聯繫。
將許可證添加到README是一個好習慣，這樣人們能夠輕鬆地引用它。
確保已在項目文件夾中添加了許可證文件。快捷方式：在GitHub中單擊repo根目錄下的添加新文件-->將文件名設置爲LICENSE -->GitHub顯示許可證模板--->選擇最適合項目的模板！
我我的添加了許可證名稱，並提供了指向它的連接，以下所示：
https://opensource.org/licenses/GPL-3.0
咱們還能夠添加一個頁腳，由於我喜歡頁腳，可使用它來傳達重要信息。
讓咱們將其製做爲圖像，由於到目前爲止你已經意識到圖像中的多媒體==酷（*請注意這個微妙的編程玩笑）。
就是這樣……你已經完成了你的訓練，小蚱蜢。如今是時候將這些想法用於你的項目了。
當你的項目與酷炫的README一塊兒啓動時，不要忘記README Sensei（很酷的推特處理想法）。
若是你認爲有幫助，請在GitHub上標星號並共享本指南。
https://towardsdatascience.com/how-to-write-an-awesome-readme-68bf4be91f8b
本文分享自微信公衆號 - 追馬Linux（zhuima_k8s）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。
