開(kāi)源最前線  猿妹綜合編譯
鏈接：https://dzone.com/articles/programmers-hate-writing-documentation-these-4-to

對(duì)于一般的程序員來(lái)說(shuō)，花費(fèi)數(shù)小時(shí)來(lái)創(chuàng)建代碼或修改現(xiàn)有代碼只是一天工作中的一部分，簡(jiǎn)而言之，當(dāng)程序員忙于他們最新的項(xiàng)目時(shí)，他們會(huì)把自己與外界隔絕，這種刻板印象還是有一定道理的。

但是你沒(méi)發(fā)現(xiàn)的是其實(shí)很多程序員還需要是保存關(guān)于他們的代碼如何工作的文檔，事實(shí)上，很多程序員都不愿意寫文檔，編程心理學(xué)的作者和專家Gerald Weinberg將其總結(jié)為“編程的蓖麻油”——換句話說(shuō)，這是一件對(duì)他們有好處但他們討厭做的事情。

如果沒(méi)有一個(gè)好的文檔，關(guān)于軟件如何運(yùn)行的信息就會(huì)缺乏，現(xiàn)如今，許多開(kāi)發(fā)者最多就是在他們編寫的代碼中留下一個(gè)基本的路線圖，但這依然不能解決代碼的終端用戶的問(wèn)題，因此，軟件開(kāi)發(fā)人員必須養(yǎng)成良好的文檔記錄習(xí)慣，這樣你的黑盒代碼才不會(huì)對(duì)其他人來(lái)說(shuō)是一個(gè)謎。

今天，和大家推薦4個(gè)不錯(cuò)的在線軟件文檔工具：

1、GitHub Pages

現(xiàn)在大多程序員都會(huì)使用通用代碼庫(kù)Github，所以對(duì)于希望保存文檔的程序員來(lái)說(shuō)，Github是一個(gè)不錯(cuò)的選擇，盡管很多人只是利用代碼庫(kù)中的readme功能來(lái)為項(xiàng)目提供簡(jiǎn)單的操作指南，但這并非是最好的辦法。

GitHub pages，它的項(xiàng)目頁(yè)面（包括文檔和手冊(cè)）提供了一個(gè)專用的托管平臺(tái)。它直接與所有GitHub存儲(chǔ)庫(kù)交互，允許開(kāi)發(fā)人員以更新代碼的方式更新文檔。最關(guān)鍵的是，用戶可以使用Jekyll，將純文本標(biāo)記轉(zhuǎn)換成成熟的靜態(tài)網(wǎng)站，而不需要額外的編程。

地址：https://pages.github.com/

2、Read the Docs

顧名思義，Read the Docs為開(kāi)發(fā)人員提供了一個(gè)集中的平臺(tái)來(lái)保存文檔，這樣用戶就可以直接閱讀文檔了。它的工作原理有點(diǎn)類似GitHub pages，因?yàn)殚_(kāi)發(fā)人員可以從他們喜歡的版本控制系統(tǒng)（包括Git、Bazaar、Mercurial等）中推送文檔更新。

不過(guò)，Read the Docs最好的部分還是它的靈活性，因此開(kāi)發(fā)人員可以自動(dòng)化大部分的文檔創(chuàng)建過(guò)程，這樣一來(lái)就可以節(jié)省大量的時(shí)間，最重要的是，平臺(tái)上的所有內(nèi)容都以多種格式向公眾開(kāi)放，形式包括pdf、HTML，電子閱讀等。

地址：https://readthedocs.org/

3、Tettra

雖然不是嚴(yán)格地作為軟件文檔平臺(tái)，但是作為一個(gè)成熟的知識(shí)庫(kù)，Tettra仍然是一個(gè)非常好的軟件文檔工具。當(dāng)一個(gè)項(xiàng)目設(shè)計(jì)到多個(gè)程序員，而非技術(shù)用戶想要了解整個(gè)項(xiàng)目細(xì)節(jié)的時(shí)候，Tettra最為適用。對(duì)于大多數(shù)軟件開(kāi)發(fā)人員來(lái)說(shuō)，Tettra在記錄與他們工作相關(guān)的常見(jiàn)問(wèn)題的答案時(shí)表現(xiàn)最為突出。

地址：https://tettra.com/

4、Apiary

盡管軟件文檔始終被認(rèn)為是關(guān)鍵任務(wù)，但是有一種類型的文檔是任何開(kāi)發(fā)人員都不能忽視的——API文檔，由于它們是軟件中最容易被外部用戶發(fā)現(xiàn)的部分，所以當(dāng)某些事情不清楚時(shí)，它們也會(huì)產(chǎn)生很多的問(wèn)題。Apiary是一個(gè)平臺(tái)，允許用戶使用Markdown編寫其文檔，包括模擬API調(diào)用。此外，該平臺(tái)允許用戶測(cè)試API，換句話說(shuō)，它既是一個(gè)文檔工具也是一個(gè)測(cè)試平臺(tái)。

地址：https://apiary.io/

長(zhǎng)按進(jìn)入小程序，進(jìn)行打卡簽到

新一期打卡簽到，獎(jiǎng)品超多

（更多精彩值得期待……）

關(guān)注后臺(tái)回復(fù)【抽獎(jiǎng)】參與抽獎(jiǎng)iPad

幾個(gè)號(hào)主共同舉辦的眾籌活動(dòng)

真實(shí)有效，沒(méi)有套路！