實(shí)際上，我想說(shuō)明的是：對于面向開(kāi)發(fā)者的產(chǎn)品來(lái)說(shuō)，其用戶(hù)體驗中最重要的一環(huán)并不是什么主頁(yè)設計、登錄過(guò)程、或者SDK下載。真正最重要的是產(chǎn)品的API文檔！如果沒(méi)人知道你的產(chǎn)品如何使用，縱使它巧奪天工，又有何用？

如果你是一個(gè)專(zhuān)門(mén)從事面向開(kāi)發(fā)者產(chǎn)品設計的工程師，那么編寫(xiě)完善的技術(shù)文檔，就跟你為終端用戶(hù)提供良好用戶(hù)體驗一樣關(guān)鍵。

我見(jiàn)過(guò)許多類(lèi)似的情況，一個(gè)項目被草率地扔到GitHub的頁(yè)面上，僅僅配有兩行的readme說(shuō)明文件。要知道，真正成功的API文檔是需要用愛(ài)來(lái)悉心制作的藝術(shù)品。在Parse產(chǎn)品項目里，我們就把自己奉獻給了這門(mén)藝術(shù)！

那么，什么才是制作優(yōu)秀API文檔的關(guān)鍵因素呢？

0. 絕不吝惜使用層次

你的設計文檔不應當僅僅直白地列出所有的終端函數和其參數。好的文檔應該是一整套有機的系統內容，能指引用戶(hù)通過(guò)文檔與API進(jìn)行交互。退一萬(wàn)步說(shuō)，你至少讓你的文檔包含以下幾個(gè)部分。

參考索引：參考索引應當是一個(gè)事無(wú)巨細的列表，包含了所有功能函數的繁文縟節。它必須注明所有的數據類(lèi)型和函數規格。高級開(kāi)發(fā)者要能夠拿著(zhù)它整天當參考書(shū)使用。

開(kāi)發(fā)指南：這是介于參考索引和開(kāi)發(fā)教程中間程度的文檔。它就仿佛是一篇更加詳細的參考索引，闡明了如何使用各種API。

開(kāi)發(fā)教程：開(kāi)發(fā)教程會(huì )更加具體地闡述如何使用API，并著(zhù)重介紹其中的一部分功能。如果能提供可編譯運行的源代碼，那就再好不過(guò)了。

在Parse項目里，我們做到了上述所有三個(gè)部分。目前我們正在努力編制更多的開(kāi)發(fā)教程。

另外一個(gè)此方面優(yōu)秀的范例是Stripe’s API（http://www.stripe.com） 。這個(gè)產(chǎn)品的文檔包括一個(gè)很棒的《hybrid guide and reference》，以及一套開(kāi)發(fā)教程�！禛itHub API參考》也經(jīng)過(guò)了良好的設計。

1. 不要在例子中包含抽象概念

你可以爭辯說(shuō)，我的API本身就是個(gè)抽象體， 抽象就是它的特點(diǎn)。然而，當你在教會(huì )開(kāi)發(fā)者如何使用的過(guò)程中，還是能不抽象就不抽象比較好。

在你的文檔中盡可能地舉現實(shí)中的例子吧。沒(méi)有哪個(gè)開(kāi)發(fā)者會(huì )抱怨你舉例太多的。實(shí)際上，這種做法能顯著(zhù)地縮短開(kāi)發(fā)者理解你產(chǎn)品的時(shí)間。對此，我們的網(wǎng)站里甚至給出一個(gè)代碼樣例加以解釋。

3. 減少點(diǎn)擊次數

開(kāi)發(fā)者痛恨點(diǎn)擊鼠標，這已經(jīng)不是什么秘密了。千萬(wàn)別把你的文檔分散在數以萬(wàn)計的頁(yè)面當中。盡量把相關(guān)的主題都放到一個(gè)頁(yè)面里。

我們非常贊成使用“單頁(yè)面大指南”的組織形式（鏈接），這種形式不僅能讓用戶(hù)縱覽全局，僅僅通過(guò)一個(gè)導航欄就能進(jìn)入他們感興趣的任意主題，另外還有一個(gè)好處是：用戶(hù)在進(jìn)行搜索的時(shí)候，僅僅搜索當前頁(yè)面，就能涵蓋查找所有的內容。

在這個(gè)方面的一個(gè)優(yōu)秀范例是ckbone.js documentation，只要你有個(gè)鼠標，一切盡在掌握。

4. 包含適當的快速指南

萬(wàn)事開(kāi)頭難，開(kāi)發(fā)者學(xué)習一套全新的API，不得不重新適應其全新的思維方式，學(xué)習代價(jià)高昂。對于這個(gè)問(wèn)題的解決辦法是：通過(guò)快速指南來(lái)引導開(kāi)發(fā)者。

快速指南的目的是讓用戶(hù)用最小的代價(jià)學(xué)習如何利用你提供的API干一些小事。僅此而已。一旦用戶(hù)完成了快速指南，他們就對自己有了信心，并能向更加深入的主題邁進(jìn)。

舉個(gè)例子，我們的快速指南能讓用戶(hù)下載SDK以及在平臺上存儲一個(gè)對象。為此，我們甚至做了一個(gè)按鈕，來(lái)讓用戶(hù)測試他們是否正確地完成了快速指南。這能提升用戶(hù)的信心，以鼓勵他們學(xué)習我們產(chǎn)品其他的部分。

5. 支持多種編程語(yǔ)言

我們生活在一個(gè)多語(yǔ)言的世界。如果可能的話(huà)，為你的API提供各種編程語(yǔ)言版本的樣例程序，只要的API支持這些語(yǔ)言。多數時(shí)候，多語(yǔ)言的工作都是由客戶(hù)端庫來(lái)完成的。要知道，開(kāi)發(fā)者要想掌握一套API，離開(kāi)他們熟悉的編程語(yǔ)言，是很難想象的。

MailGun’s API為此做出了良好的榜樣。它提供了curl，Ruby，Python，Java，C#和PHP等多個(gè)版本供開(kāi)發(fā)者選擇。

6. 絕不放過(guò)任何邊界情況

使用API開(kāi)發(fā)應用，所能遭遇的最糟糕的情況，莫過(guò)于你發(fā)現了一個(gè)文檔中沒(méi)有提到的錯誤。如果你遇到這種情況，就意味著(zhù)你不能確認究竟是你的程序出了錯，還是你對API的理解出了錯。

因此，參考索引中必須包含每種假設可能造成的邊界情況，不論是顯示的還是隱式的�；�點(diǎn)兒時(shí)間在這個(gè)上面，絕對能起到事半功倍的效果。

7. 提供樣例應用

在學(xué)習結束的時(shí)候，開(kāi)發(fā)者希望能看到關(guān)于項目產(chǎn)品應用的大致藍圖。達到這一目的最好的辦法，莫過(guò)于提供可運行的樣例應用。我發(fā)現，應用程序代碼是將API運行機理和系統整合融會(huì )貫通最好的辦法。

sample code in Apple’s iOS Developer Library 則是這方面做得很好的，它包含了詳盡的iOS樣例程序，并按主題一一分類(lèi)。

8. 加入人性化的因素

閱讀技術(shù)文檔枯燥乏味，自然不像坐過(guò)山車(chē)那樣緊張刺激。不過(guò)，你至少可以通過(guò)加入一些人性化的因素，或者開(kāi)開(kāi)玩笑。給你的例子中的變量其一些好玩兒的名字吧，別老是把函數名稱(chēng)叫什么foo之類(lèi)的，好讓你的讀者有煥然一新的感覺(jué)。