- 簡(jiǎn)體
- 簡(jiǎn)體中文 English
如何自作高質(zhì)量的API文檔
實(shí)際上,我想說明的是:對(duì)于面向開發(fā)者的產(chǎn)品來說,其用戶體驗(yàn)中最重要的一環(huán)并不是什么主頁設(shè)計(jì)、登錄過程、或者SDK下載。真正最重要的是產(chǎn)品的API文檔!如果沒人知道你的產(chǎn)品如何使用,縱使它巧奪天工,又有何用?
如果你是一個(gè)專門從事面向開發(fā)者產(chǎn)品設(shè)計(jì)的工程師,那么編寫完善的技術(shù)文檔,就跟你為終端用戶提供良好用戶體驗(yàn)一樣關(guān)鍵。
我見過許多類似的情況,一個(gè)項(xiàng)目被草率地扔到GitHub的頁面上,僅僅配有兩行的readme說明文件。要知道,真正成功的API文檔是需要用愛來悉心制作的藝術(shù)品。在Parse產(chǎn)品項(xiàng)目里,我們就把自己奉獻(xiàn)給了這門藝術(shù)!
那么,什么才是制作優(yōu)秀API文檔的關(guān)鍵因素呢?
1. 絕不吝惜使用層次
你的設(shè)計(jì)文檔不應(yīng)當(dāng)僅僅直白地列出所有的終端函數(shù)和其參數(shù)。好的文檔應(yīng)該是一整套有機(jī)的系統(tǒng)內(nèi)容,能指引用戶通過文檔與API進(jìn)行交互。退一萬步說,你至少讓你的文檔包含以下幾個(gè)部分。
參考索引:參考索引應(yīng)當(dāng)是一個(gè)事無巨細(xì)的列表,包含了所有功能函數(shù)的繁文縟節(jié)。它必須注明所有的數(shù)據(jù)類型和函數(shù)規(guī)格。高級(jí)開發(fā)者要能夠拿著它整天當(dāng)參考書使用。
開發(fā)指南:這是介于參考索引和開發(fā)教程中間程度的文檔。它就仿佛是一篇更加詳細(xì)的參考索引,闡明了如何使用各種API。
開發(fā)教程:開發(fā)教程會(huì)更加具體地闡述如何使用API,并著重介紹其中的一部分功能。如果能提供可編譯運(yùn)行的源代碼,那就再好不過了。
在Parse項(xiàng)目里,我們做到了上述所有三個(gè)部分。目前我們正在努力編制更多的開發(fā)教程。
另外一個(gè)此方面優(yōu)秀的范例是Stripe’s API(http://www.stripe.com) 。這個(gè)產(chǎn)品的文檔包括一個(gè)很棒的《hybrid guide and reference》,以及一套開發(fā)教程?!禛itHub API參考》也經(jīng)過了良好的設(shè)計(jì)。
你可以爭(zhēng)辯說,我的API本身就是個(gè)抽象體, 抽象就是它的特點(diǎn)。然而,當(dāng)你在教會(huì)開發(fā)者如何使用的過程中,還是能不抽象就不抽象比較好。
在你的文檔中盡可能地舉現(xiàn)實(shí)中的例子吧。沒有哪個(gè)開發(fā)者會(huì)抱怨你舉例太多的。實(shí)際上,這種做法能顯著地縮短開發(fā)者理解你產(chǎn)品的時(shí)間。對(duì)此,我們的網(wǎng)站里甚至給出一個(gè)代碼樣例加以解釋。
2. 減少點(diǎn)擊次數(shù)
開發(fā)者痛恨點(diǎn)擊鼠標(biāo),這已經(jīng)不是什么秘密了。千萬別把你的文檔分散在數(shù)以萬計(jì)的頁面當(dāng)中。盡量把相關(guān)的主題都放到一個(gè)頁面里。
我們非常贊成使用“單頁面大指南”的組織形式(鏈接),這種形式不僅能讓用戶縱覽全局,僅僅通過一個(gè)導(dǎo)航欄就能進(jìn)入他們感興趣的任意主題,另外還有一個(gè)好處是:用戶在進(jìn)行搜索的時(shí)候,僅僅搜索當(dāng)前頁面,就能涵蓋查找所有的內(nèi)容。
在這個(gè)方面的一個(gè)優(yōu)秀范例是ckbone.js documentation,只要你有個(gè)鼠標(biāo),一切盡在掌握。
萬事開頭難,開發(fā)者學(xué)習(xí)一套全新的API,不得不重新適應(yīng)其全新的思維方式,學(xué)習(xí)代價(jià)高昂。對(duì)于這個(gè)問題的解決辦法是:通過快速指南來引導(dǎo)開發(fā)者。
快速指南的目的是讓用戶用最小的代價(jià)學(xué)習(xí)如何利用你提供的API干一些小事。僅此而已。一旦用戶完成了快速指南,他們就對(duì)自己有了信心,并能向更加深入的主題邁進(jìn)。
舉個(gè)例子,我們的快速指南能讓用戶下載SDK以及在平臺(tái)上存儲(chǔ)一個(gè)對(duì)象。為此,我們甚至做了一個(gè)按鈕,來讓用戶測(cè)試他們是否正確地完成了快速指南。這能提升用戶的信心,以鼓勵(lì)他們學(xué)習(xí)我們產(chǎn)品其他的部分。
3. 支持多種編程語言
我們生活在一個(gè)多語言的世界。如果可能的話,為你的API提供各種編程語言版本的樣例程序,只要的API支持這些語言。多數(shù)時(shí)候,多語言的工作都是由客戶端庫來完成的。要知道,開發(fā)者要想掌握一套API,離開他們熟悉的編程語言,是很難想象的。
MailGun’s API為此做出了良好的榜樣。它提供了curl,Ruby,Python,Java,C#和PHP等多個(gè)版本供開發(fā)者選擇。
4. 絕不放過任何邊界情況
使用API開發(fā)應(yīng)用,所能遭遇的最糟糕的情況,莫過于你發(fā)現(xiàn)了一個(gè)文檔中沒有提到的錯(cuò)誤。如果你遇到這種情況,就意味著你不能確認(rèn)究竟是你的程序出了錯(cuò),還是你對(duì)API的理解出了錯(cuò)。
因此,參考索引中必須包含每種假設(shè)可能造成的邊界情況,不論是顯示的還是隱式的?;c(diǎn)兒時(shí)間在這個(gè)上面,絕對(duì)能起到事半功倍的效果。
在學(xué)習(xí)結(jié)束的時(shí)候,開發(fā)者希望能看到關(guān)于項(xiàng)目產(chǎn)品應(yīng)用的大致藍(lán)圖。達(dá)到這一目的最好的辦法,莫過于提供可運(yùn)行的樣例應(yīng)用。我發(fā)現(xiàn),應(yīng)用程序代碼是將API運(yùn)行機(jī)理和系統(tǒng)整合融會(huì)貫通最好的辦法。
sample code in Apple’s iOS Developer Library 則是這方面做得很好的,它包含了詳盡的iOS樣例程序,并按主題一一分類。
5. 加入人性化的因素
閱讀技術(shù)文檔枯燥乏味,自然不像坐過山車那樣緊張刺激。不過,你至少可以通過加入一些人性化的因素,或者開開玩笑。給你的例子中的變量其一些好玩兒的名字吧,別老是把函數(shù)名稱叫什么foo之類的,好讓你的讀者有煥然一新的感覺。
至少,這可以保證你的讀者不會(huì)讀著讀著就睡過去。
本文發(fā)布于北京網(wǎng)站制作公司尚品中國http://m.proteomeinstitute.com/
建站流程
-
網(wǎng)站需求
-
網(wǎng)站策劃方案
-
頁面設(shè)計(jì)風(fēng)格
-
確認(rèn)交付使用
-
資料錄入優(yōu)化
-
程序設(shè)計(jì)開發(fā)
-
后續(xù)跟蹤服務(wù)
-
聯(lián)系電話
010-60259772
熱門標(biāo)簽
- 網(wǎng)站建設(shè)
- 食品網(wǎng)站建設(shè)
- 微信小程序開發(fā)
- 小程序開發(fā)
- 無錫網(wǎng)站建設(shè)
- 研究所網(wǎng)站建設(shè)
- 沈陽網(wǎng)站建設(shè)
- 廊坊網(wǎng)站建設(shè)
- 鄭州網(wǎng)站建設(shè)
- 婚紗攝影網(wǎng)站建設(shè)
- 手機(jī)端網(wǎng)站建設(shè)
- 高校網(wǎng)站制作
- 天津網(wǎng)站建設(shè)
- 教育網(wǎng)站建設(shè)
- 品牌網(wǎng)站建設(shè)
- 政府網(wǎng)站建設(shè)
- 北京網(wǎng)站建設(shè)
- 網(wǎng)站設(shè)計(jì)
- 網(wǎng)站制作
最新文章
推薦新聞
更多行業(yè)-
如何建設(shè)成功的個(gè)人網(wǎng)站
【要明確建網(wǎng)站的目的】在網(wǎng)站建設(shè)之前,首先要明確自己的建站目的,有很多...
2015-01-08 -
網(wǎng)站建設(shè)收費(fèi)項(xiàng)一般可以包括哪些
北京網(wǎng)站建設(shè)收費(fèi)項(xiàng)一般可以包括以下一些素材整理階段的文字錄入費(fèi), 市場(chǎng)...
2012-09-12 -
什么原因造成糟糕的網(wǎng)頁設(shè)計(jì)?
1、太多的色彩背景一種顏色,內(nèi)容文本一種顏色,鏈接一種顏色,頁頭和li...
2018-08-11 -
科研網(wǎng)站制作成功的要素是什么?
網(wǎng)站是成功的在線商業(yè)最重要的組成部分之一,但是在這個(gè)競(jìng)爭(zhēng)激烈的虛擬世界...
2022-01-20 -
網(wǎng)站設(shè)計(jì)之字體如何設(shè)置
我曾與一位視覺設(shè)計(jì)師合作共同開發(fā)一款web應(yīng)用。他提交給我的設(shè)計(jì)稿看起...
2014-05-16 -
山東網(wǎng)站設(shè)計(jì)是不是需要保持與時(shí)俱進(jìn)的思維模式?
隨著互聯(lián)網(wǎng)的不斷發(fā)展,那么企業(yè)網(wǎng)站設(shè)計(jì)的技術(shù)也在不斷發(fā)展,同時(shí)用戶的審...
2019-04-16
預(yù)約專業(yè)咨詢顧問溝通!
免責(zé)聲明
非常感謝您訪問我們的網(wǎng)站。在您使用本網(wǎng)站之前,請(qǐng)您仔細(xì)閱讀本聲明的所有條款。
1、本站部分內(nèi)容來源自網(wǎng)絡(luò),涉及到的部分文章和圖片版權(quán)屬于原作者,本站轉(zhuǎn)載僅供大家學(xué)習(xí)和交流,切勿用于任何商業(yè)活動(dòng)。
2、本站不承擔(dān)用戶因使用這些資源對(duì)自己和他人造成任何形式的損失或傷害。
3、本聲明未涉及的問題參見國家有關(guān)法律法規(guī),當(dāng)本聲明與國家法律法規(guī)沖突時(shí),以國家法律法規(guī)為準(zhǔn)。
4、如果侵害了您的合法權(quán)益,請(qǐng)您及時(shí)與我們,我們會(huì)在第一時(shí)間刪除相關(guān)內(nèi)容!
聯(lián)系方式:010-60259772
電子郵件:394588593@qq.com