編寫技術(shù)文檔，API文檔優(yōu)質(zhì)的編寫方法，是令眾多開(kāi)發(fā)者望而生畏的任務(wù)之一。它本身是一件費(fèi)時(shí)費(fèi)力才能做好的工作。可是大多數(shù)時(shí)候，人們卻總是想抄抄捷徑，這樣做的結(jié)果往往非常令人遺憾的，因?yàn)閮?yōu)質(zhì)的技術(shù)文檔是決定你的項(xiàng)目是否引人關(guān)注的重要因素。無(wú)論開(kāi)源產(chǎn)品或面向開(kāi)發(fā)者的產(chǎn)品，均是如此。

使用API開(kāi)發(fā)應(yīng)用，所能遭遇的最糟糕的情況，莫過(guò)于你發(fā)現(xiàn)了一個(gè)文檔中沒(méi)有提到的錯(cuò)誤。《GitHub API參考》也經(jīng)由了良好的設(shè)計(jì)。

我們糊口在一個(gè)多語(yǔ)言的世界。

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

舉個(gè)例子，我們的快速指南能讓用戶下載SDK以及在平臺(tái)上存儲(chǔ)一個(gè)對(duì)象。

2. 減少點(diǎn)擊次數(shù)

在你的文檔中盡可能地舉現(xiàn)實(shí)中的例子吧。

參考索引：參考索引應(yīng)當(dāng)是一個(gè)事無(wú)巨細(xì)的列表，包含了所有功能函數(shù)的繁文縟節(jié)。

在學(xué)習(xí)結(jié)束的時(shí)候，開(kāi)發(fā)者但愿能看到關(guān)于項(xiàng)目產(chǎn)品應(yīng)用的大致藍(lán)圖。它必需注明所有的數(shù)據(jù)類型和函數(shù)規(guī)格。我發(fā)現(xiàn)，應(yīng)用程序代碼是將API運(yùn)行機(jī)理和系統(tǒng)整合融會(huì)貫通最好的辦法。

3. 提供樣例應(yīng)用

因此，參考索引中必需包含每種假設(shè)可能造成的邊界情況，不論是顯示的仍是隱式的。然而，當(dāng)你在教會(huì)開(kāi)發(fā)者如何使用的過(guò)程中，仍是能不抽象就不抽象比較好。

你的設(shè)計(jì)文檔不應(yīng)當(dāng)僅僅直白地列出所有的終端函數(shù)和其參數(shù)。它就仿佛是一篇更加具體的參考索引，闡明了如何使用各種API。目前我們正在努力編制更多的開(kāi)發(fā)教程。假如能提供可編譯運(yùn)行的源代碼，那就再好不外了。

4. 毫不放過(guò)任何邊界情況

MailGun’s API為此做出了良好的榜樣。
閱讀技術(shù)文檔枯燥乏味，天然不像坐過(guò)山車那樣緊張刺激。僅此而已。

在Parse項(xiàng)目里，我們做到了上述所有三個(gè)部門。高級(jí)開(kāi)發(fā)者要能夠拿著它整天當(dāng)參考書使用。對(duì)此，我們的網(wǎng)站里甚至給出一個(gè)代碼樣例加以解釋。

5. 加入人道化的因素

sample code in Apple’s iOS Developer Library 則是這方面做得很好的，它包含了詳盡的iOS樣例程序，并按主題逐一分類。給你的例子中的變量其一些好玩兒的名字吧，別總是把函數(shù)名稱叫什么foo之類的，好讓你的讀者有煥然一新的感覺(jué)。

快速指南的目的是讓用戶用最小的代價(jià)學(xué)習(xí)如何利用你提供的API干一些小事。

萬(wàn)事開(kāi)頭難，開(kāi)發(fā)者學(xué)習(xí)一套全新的API，不得不重新適應(yīng)其全新的思維方式，學(xué)習(xí)代價(jià)高昂。
你可以爭(zhēng)辯說(shuō)，我的API本身就是個(gè)抽象體， 抽象就是它的特點(diǎn)。它提供了curl，Ruby，Python，Java，C#和PHP等多個(gè)版本供開(kāi)發(fā)者選擇。要知道，真正成功的API文檔是需要用愛(ài)來(lái)悉心制作的藝術(shù)品。

至少，這可以保證你的讀者不會(huì)讀著讀著就睡過(guò)去。API文檔優(yōu)質(zhì)的編寫方法，實(shí)際上，這種做法能明顯地縮短開(kāi)發(fā)者理解你產(chǎn)品的時(shí)間。千萬(wàn)別把你的文檔分散在數(shù)以萬(wàn)計(jì)的頁(yè)面當(dāng)中。為此，我們甚至做了一個(gè)按鈕，來(lái)讓用戶測(cè)試他們是否準(zhǔn)確地完成了快速指南。真正最重要的是產(chǎn)品的API文檔！假如沒(méi)人知道你的產(chǎn)品如何使用，縱使它巧奪天工，又有何用？

這能晉升用戶的決心信念，以鼓勵(lì)他們學(xué)習(xí)我們產(chǎn)品其他的部門。達(dá)到這一目的最好的辦法，莫過(guò)于提供可運(yùn)行的樣例應(yīng)用。多數(shù)時(shí)候，多語(yǔ)言的工作都是由客戶端庫(kù)來(lái)完成的。要知道，開(kāi)發(fā)者要想把握一套API，離開(kāi)他們認(rèn)識(shí)的編程語(yǔ)言，是很難想象的。盡量把相關(guān)的主題都放到一個(gè)頁(yè)面里。不外，你至少可以通過(guò)加入一些人道化的因素，或者開(kāi)開(kāi)玩笑。對(duì)于這個(gè)題目的解決辦法是：通過(guò)快速指南來(lái)引導(dǎo)開(kāi)發(fā)者。一旦用戶完成了快速指南，他們就對(duì)自己有了決心信念，并能向更加深入的主題邁進(jìn)。在Parse產(chǎn)品項(xiàng)目里，我們就把自己奉獻(xiàn)給了這門藝術(shù)！

假如你是一個(gè)專門從事面向開(kāi)發(fā)者產(chǎn)品設(shè)計(jì)的工程師，那么編寫完善的技術(shù)文檔，就跟你為終端用戶提供良好用戶體驗(yàn)一樣樞紐。假如你碰到這種情況，就意味著你不能確認(rèn)畢竟是你的程序出了錯(cuò)，仍是你對(duì)API的理解出了錯(cuò)。花點(diǎn)兒時(shí)間在這個(gè)上面，絕對(duì)能起到事半功倍的效果。

開(kāi)發(fā)教程：開(kāi)發(fā)教程會(huì)更加詳細(xì)地闡述如何使用API，并著重先容其中的一部門功能。

實(shí)際上，我想說(shuō)明的是：對(duì)于面向開(kāi)發(fā)者的產(chǎn)品來(lái)說(shuō)，其用戶體驗(yàn)中最重要的一環(huán)并不是什么主頁(yè)設(shè)計(jì)、登錄過(guò)程、或者SDK下載。這個(gè)產(chǎn)品的文檔包括一個(gè)很棒的《hybrid guide and reference》，以及一套開(kāi)發(fā)教程。

開(kāi)發(fā)者痛恨點(diǎn)擊鼠標(biāo)，這已經(jīng)不是什么秘密了。

6. 包含適當(dāng)?shù)目焖僦改?/P>

在這個(gè)方面的一個(gè)優(yōu)秀范例是ckbone.js documentation，只要你有個(gè)鼠標(biāo)，一切盡在把握。沒(méi)有哪個(gè)開(kāi)發(fā)者會(huì)訴苦你舉例太多的。好的文檔應(yīng)該是一整套有機(jī)的系統(tǒng)內(nèi)容，能指引用戶通過(guò)文檔與API進(jìn)行交互。退一萬(wàn)步說(shuō)，你至少讓你的文檔包含以下幾個(gè)部門。

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

另外一個(gè)此方面優(yōu)秀的范例是Stripe’s API（http://www.stripe.com） 。

開(kāi)發(fā)指南：這是介于參考索引和開(kāi)發(fā)教程中間程度的文檔。

8. 毫不吝惜使用層次

那么，什么才是制作優(yōu)秀API文檔的樞紐因素呢？

我見(jiàn)過(guò)很多類似的情況，一個(gè)項(xiàng)目被草率地扔到GitHub的頁(yè)面上，僅僅配有兩行的readme說(shuō)明文件。