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

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

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

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

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

1. 千萬不要在層次上吝嗇

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.支持多種編程語言

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

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

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

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

因此，每

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