北京網(wǎng)站建設(shè)公司推來(lái)客：編寫(xiě)技術(shù)文檔是許多網(wǎng)站制作開(kāi)發(fā)人員最頭疼的工作之一。做好這件事本身就是一件費(fèi)時(shí)費(fèi)力的工作。但是很多時(shí)候，人們總是想抄捷徑，而這樣做的結(jié)果往往是非常令人遺憾的，因?yàn)楦哔|(zhì)量的技術(shù)文檔是決定你的項(xiàng)目是否受到關(guān)注的重要因素。對(duì)于開(kāi)源產(chǎn)品和面向開(kāi)發(fā)人員的產(chǎn)品都是如此。

其實(shí)我想說(shuō)的是，面向開(kāi)發(fā)者的產(chǎn)品，最重要的用戶體驗(yàn)不是首頁(yè)設(shè)計(jì)、登錄流程、SDK下載。最重要的是產(chǎn)品的API文檔！如果沒(méi)有人知道如何使用它，即使它工作出色，你的產(chǎn)品又有什么用呢？

如果您是專門為開(kāi)發(fā)人員設(shè)計(jì)產(chǎn)品的工程師，那么編寫(xiě)完善的技術(shù)文檔與為最終用戶提供良好的用戶體驗(yàn)一樣重要。

我見(jiàn)過(guò)很多類似的情況，一個(gè)項(xiàng)目被粗心地扔到GitHub 頁(yè)面上，除了兩行自述文件外什么都沒(méi)有。要知道，真正成功的API 文檔是一件用愛(ài)精心打造的藝術(shù)品。在Parse 產(chǎn)品項(xiàng)目中，我們致力于這門藝術(shù)！

那么，好的API 文檔的關(guān)鍵要素是什么？

1. 千萬(wàn)不要在層次上吝嗇

您的設(shè)計(jì)文檔不應(yīng)只是簡(jiǎn)單地列出所有終端功能及其參數(shù)。一個(gè)好的文檔應(yīng)該是一套有機(jī)的系統(tǒng)內(nèi)容，能夠引導(dǎo)用戶通過(guò)文檔與API進(jìn)行交互。退一步說(shuō)，你至少應(yīng)該讓你的文檔包含以下部分。

參考索引：參考索引應(yīng)該是一個(gè)詳細(xì)的列表，包括所有功能的繁文縟節(jié)。它必須注釋所有數(shù)據(jù)類型和函數(shù)規(guī)范。高級(jí)開(kāi)發(fā)人員應(yīng)該可以整天拿著它，把它當(dāng)作參考書(shū)來(lái)使用。

開(kāi)發(fā)指南：這是介于參考索引和開(kāi)發(fā)教程之間的文檔。它就像一份更詳細(xì)的參考資料，解釋了如何使用各種API。

開(kāi)發(fā)教程：開(kāi)發(fā)教程會(huì)更具體地講解API的使用方法，重點(diǎn)介紹其部分功能。如果能提供可以編譯運(yùn)行的源碼就更好了。

在Parse 項(xiàng)目中，我們執(zhí)行上述所有三個(gè)操作。我們目前正在努力編寫(xiě)更多的開(kāi)發(fā)教程。

另一個(gè)很好的例子是Stripe 的API (http://www.stripe.com)。該產(chǎn)品的文檔包括一個(gè)很棒的《hybrid guide and reference》 和一組開(kāi)發(fā)教程?！禛itHub API參考》也設(shè)計(jì)的不錯(cuò)。

你可以說(shuō)我的API本身就是一種抽象，抽象就是它的特點(diǎn)。但是，當(dāng)你在教開(kāi)發(fā)人員如何使用它時(shí)，最好不要抽象或不抽象。

在您的文檔中盡可能使用真實(shí)示例。沒(méi)有開(kāi)發(fā)人員會(huì)抱怨你舉了太多的例子。事實(shí)上，這樣做可以顯著減少開(kāi)發(fā)人員了解您的產(chǎn)品所需的時(shí)間。我們的網(wǎng)站上什至有一個(gè)代碼示例來(lái)解釋這一點(diǎn)。

2. 更少的點(diǎn)擊

開(kāi)發(fā)人員討厭點(diǎn)擊鼠標(biāo)已經(jīng)不是什么秘密了。切勿將您的文檔分散在數(shù)萬(wàn)頁(yè)上。嘗試將相關(guān)主題放在一頁(yè)中。

我們非常贊成使用“一頁(yè)指南”的組織形式（鏈接）。這種形式不僅可以讓用戶縱覽全局，還可以通過(guò)一個(gè)導(dǎo)航欄進(jìn)入任何他們感興趣的話題。另一個(gè)好處是，用戶在搜索時(shí)，只要搜索當(dāng)前頁(yè)面，就可以找到所有的內(nèi)容。

一個(gè)很好的例子就是ckbone.js 文檔，只要你有鼠標(biāo)，一切都在控制之中。

萬(wàn)事開(kāi)頭難。開(kāi)發(fā)人員學(xué)習(xí)一組新的API，必須重新適應(yīng)他們的新思維方式。學(xué)習(xí)成本很高。這個(gè)問(wèn)題的解決方案是通過(guò)快速指南來(lái)指導(dǎo)開(kāi)發(fā)人員。

快速指南的目的是讓用戶學(xué)習(xí)如何使用您提供的API 以最小的努力做一些小事情。就這樣。用戶完成快速指南后，他們就會(huì)對(duì)自己充滿信心，并可以繼續(xù)討論更深入的主題。

例如，我們的快速指南允許用戶下載SDK 并將對(duì)象存儲(chǔ)在平臺(tái)上。為此，我們甚至制作了一個(gè)按鈕，讓用戶測(cè)試他們是否正確完成了快速指南。這會(huì)增強(qiáng)用戶信心并鼓勵(lì)他們了解我們產(chǎn)品的其他部分。

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

我們生活在一個(gè)多語(yǔ)言的世界。如果可能，請(qǐng)以各種編程語(yǔ)言為您的API 提供示例程序，只要您的API 支持這些語(yǔ)言。大多數(shù)時(shí)候，多語(yǔ)言工作是由客戶端庫(kù)完成的。要知道，開(kāi)發(fā)者要想掌握一套API，離開(kāi)自己熟悉的編程語(yǔ)言是很難想象的。

MailGun 的API 就是一個(gè)很好的例子。它提供了curl、Ruby、Python、Java、C#和PHP多個(gè)版本供開(kāi)發(fā)者選擇。

4. 永遠(yuǎn)不要放過(guò)任何邊緣情況

使用API 開(kāi)發(fā)應(yīng)用程序最糟糕的事情是發(fā)現(xiàn)文檔中未提及的錯(cuò)誤。如果遇到這種情況，說(shuō)明你無(wú)法確認(rèn)是你的程序有問(wèn)題，還是你對(duì)API的理解有誤。

因此，每

我們專注高端建站，小程序開(kāi)發(fā)、軟件系統(tǒng)定制開(kāi)發(fā)、BUG修復(fù)、物聯(lián)網(wǎng)開(kāi)發(fā)、各類API接口對(duì)接開(kāi)發(fā)等。十余年開(kāi)發(fā)經(jīng)驗(yàn)，每一個(gè)項(xiàng)目承諾做到滿意為止，多一次對(duì)比，一定讓您多一份收獲！