How to Write a README on GitHub

最近在寫 GitHub 上的 README,發現這個東西好像每個人的寫法都不太一樣,於是稍微整理了一下自己覺得大概要包含哪些內容。

Motivation

顧名思義就是簡介一下為什麼會有這個專案,以及這個專案大概在做什麼,解決了什麼問題。最好是三到五句話講出重點,不然很多人看到落落長的文章可能就跳過了 XD

Getting Started / Installation

如何快速地開始使用這個專案,通常會包含安裝以及環境設定等等。

Example / Demo

一個簡單有力的範例可以讓大家更容易了解這個專案在做什麼,也有人會將這段與 Getting Started 整合在一起。基本上我在 survey 任何東西都是先找這段來看,所以可以放越前面越好。如果可以的話,提供一個線上的 Demo 也是很好的選擇。

簡單來說就是,Show Me the Code!

Overview

列出這個專案使用到哪些 3rd party 的工具或是 library。這可能會是開發者在選擇上一個重要的參考依據。

API Reference

這邊開始就進入比較詳細的設定。包含提供哪些 API 可以使用,或是一些客製化的選項。

Development / Tests

如何進行開發,或是測試。

Contributors

列出這個專案的主要貢獻者以及 GitHub 或是 Twitter 帳號,讓大家知道有 bug 要找誰解

License

這個專案使用的 License。

根據專案性質或是其他狀況,可能會多多少少有些不同。不過只要大致上照這個方向去寫,就可以寫出一個像樣的 README 惹 XD

參考資料:https://gist.github.com/jxson/1784669