最近，我又挖了幾個開源項目的坑，Ledge、Ledge Framwork、Igso 等等。每次挖新坑的時候，經常性地都要花很多的時間，想着怎麼編寫 README、完善 README。而就是這麼一個簡單的 README 的編寫，它都要花費我相當長的時間，或是幾個小時，或是幾天。
問題來了，我真的是在寫 README 嗎？
引子 1：不止自述的 README
README，又稱“自述文件”，是隨着軟件發佈的一種說明文件，裏面通常包含有軟件的描述或使用的注意事項。
在衆多的開源項目裏，README 是我們最常修改的文件之一。每當我們添加了一個新的功能，一個新的特性的時候，我們的第一反應就是更新一下 README，以向世人宣告我們的開源產品又添加了新的功能。
所以，在我的那本《GitHub 漫遊指南》裏，其中有一部分的話題就是關於 README 的編寫。對於一個 README 來說，有這麼幾個關鍵要素：
一句話簡介。這個項目做什麼？
項目介紹。它解決了什麼問題
特性。包含已完成和待辦
使用指南。如何一步步使用這個項目
示例。hello, world 示例
開源協議。
對於某些項目來說，它們還有：
項目對比。如性能、特性等
……
其中的一個主要原因是，在開源領域 GitHub 有比較高的話語權。而 GitHub 使用了 README 作爲項目的『首頁』，作爲了整個開源項目門房。而正是這個首頁，讓我們重新意識到 README 的重要性，刷新了 README 的作用。
引子 2：產品而非項目
緊接着，在上一篇文章裏，我強調了開源產品而非項目。再重新以產品化的維度來考慮 README 的幾個要素，我們就有了者的對應關係
電梯演講 <-> 一句話簡介
用戶旅程 <-> 項目介紹
競品分析 <-> 項目對比
用戶故事 <-> 待辦清單
示例和使用指南 <-> 用戶手冊
……
換句話來說，通過編寫這個 README 的同時，相當於是一次關於這個開源項目的產品化思考。
README 驅動開發
由於，看不到一個成熟的 RDD 定義，所以我先按我的理解定義出第一個版本的 README 驅動開發：
README 驅動開發是一種通過事先編寫 README 的方式，以一步步驅動出受用戶歡迎產品的軟件開發方法論。它被廣泛的應用在開源軟件領域，旨在通過從使用者的視角來思考軟件的意義和用戶體驗等。
從這個角度來看的話，在編寫 README 的時候，我們要讓使用者能：
一眼能理解項目的目的。
快速瞭解項目的效果。即通過截圖或者是線上 DEMO 等方式
迅速地獲得反饋。即我只需要執行一個命令，或者是打開網頁，就能知道的效果。
知曉他她們的權利與義務。即 LICENSE
……
也就是爲什麼 README First 在開源領域非常流行的原因。
README First
README First 即通過先編寫 README 的方式來：
重新思考項目的價值，而無需真正動手寫代碼。
吸引更多的潛在用戶或者是開發者。
做正確的事情。
構建更好的開發者體驗。
它遠遠要比你做完一個開源項目，再去編寫 README 來得快速、可靠。特別是，對於 GitHub 這樣的開源平臺來說，當別人爲你的項目 star 的時候，他/她的 followers 就可以看到這個動態，進一步地提升項目的傳播效果，進一步地爲你帶來更多的 star。
而如果你的項目的 README 不夠吸引人的時候，那麼你就失去了這種先發優勢。
持續更新
它是一份初期的文檔，隨着項目的進行，越來越多的需求將會由社區反饋過來，文檔也會越來越完善。
README 測試
順便一提，最近我開始在尋找一種新的測試方式，README 測試。
既然一個 README 可以寫成結構化的，那麼它必然也是可以測試的。它可以是類似於 Gauge、Cucumber 等這樣的 BDD 框架，也可以是解析 markdown 後生成的特定的測試用例。
結論
程序員恨別人不寫文檔，自己恨寫文檔。
README 就是一個輕量級的文檔方案。