2022-06-11 分類: 網站建設
編寫技術文檔,API文檔優質的編寫方法,是令眾多開發者望而生畏的任務之一。它本身是一件費時費力才能做好的工作。可是大多數時候,人們卻總是想抄抄捷徑,這樣做的結果往往非常令人遺憾的,因為優質的技術文檔是決定你的項目是否引人關注的重要因素。無論開源產品或面向開發者的產品,均是如此。
使用API開發應用,所能遭遇的最糟糕的情況,莫過于你發現了一個文檔中沒有提到的錯誤?!禛itHub API參考》也經由了良好的設計。
我們糊口在一個多語言的世界。
1. 支持多種編程語言
舉個例子,我們的快速指南能讓用戶下載SDK以及在平臺上存儲一個對象。
2. 減少點擊次數
在你的文檔中盡可能地舉現實中的例子吧。
參考索引:參考索引應當是一個事無巨細的列表,包含了所有功能函數的繁文縟節。
在學習結束的時候,開發者但愿能看到關于項目產品應用的大致藍圖。它必需注明所有的數據類型和函數規格。我發現,應用程序代碼是將API運行機理和系統整合融會貫通最好的辦法。
3. 提供樣例應用
因此,參考索引中必需包含每種假設可能造成的邊界情況,不論是顯示的仍是隱式的。然而,當你在教會開發者如何使用的過程中,仍是能不抽象就不抽象比較好。
你的設計文檔不應當僅僅直白地列出所有的終端函數和其參數。它就仿佛是一篇更加具體的參考索引,闡明了如何使用各種API。目前我們正在努力編制更多的開發教程。假如能提供可編譯運行的源代碼,那就再好不外了。
4. 毫不放過任何邊界情況
MailGun’s API為此做出了良好的榜樣。
閱讀技術文檔枯燥乏味,天然不像坐過山車那樣緊張刺激。僅此而已。
在Parse項目里,我們做到了上述所有三個部門。高級開發者要能夠拿著它整天當參考書使用。對此,我們的網站里甚至給出一個代碼樣例加以解釋。
5. 加入人道化的因素
sample code in Apple’s iOS Developer Library 則是這方面做得很好的,它包含了詳盡的iOS樣例程序,并按主題逐一分類。給你的例子中的變量其一些好玩兒的名字吧,別總是把函數名稱叫什么foo之類的,好讓你的讀者有煥然一新的感覺。
快速指南的目的是讓用戶用最小的代價學習如何利用你提供的API干一些小事。
萬事開頭難,開發者學習一套全新的API,不得不重新適應其全新的思維方式,學習代價高昂。
你可以爭辯說,我的API本身就是個抽象體, 抽象就是它的特點。它提供了curl,Ruby,Python,Java,C#和PHP等多個版本供開發者選擇。要知道,真正成功的API文檔是需要用愛來悉心制作的藝術品。
至少,這可以保證你的讀者不會讀著讀著就睡過去。API文檔優質的編寫方法,實際上,這種做法能明顯地縮短開發者理解你產品的時間。千萬別把你的文檔分散在數以萬計的頁面當中。為此,我們甚至做了一個按鈕,來讓用戶測試他們是否準確地完成了快速指南。真正最重要的是產品的API文檔!假如沒人知道你的產品如何使用,縱使它巧奪天工,又有何用?
這能晉升用戶的決心信念,以鼓勵他們學習我們產品其他的部門。達到這一目的最好的辦法,莫過于提供可運行的樣例應用。多數時候,多語言的工作都是由客戶端庫來完成的。要知道,開發者要想把握一套API,離開他們認識的編程語言,是很難想象的。盡量把相關的主題都放到一個頁面里。不外,你至少可以通過加入一些人道化的因素,或者開開玩笑。對于這個題目的解決辦法是:通過快速指南來引導開發者。一旦用戶完成了快速指南,他們就對自己有了決心信念,并能向更加深入的主題邁進。在Parse產品項目里,我們就把自己奉獻給了這門藝術!
假如你是一個專門從事面向開發者產品設計的工程師,那么編寫完善的技術文檔,就跟你為終端用戶提供良好用戶體驗一樣樞紐。假如你碰到這種情況,就意味著你不能確認畢竟是你的程序出了錯,仍是你對API的理解出了錯?;c兒時間在這個上面,絕對能起到事半功倍的效果。
開發教程:開發教程會更加詳細地闡述如何使用API,并著重先容其中的一部門功能。
實際上,我想說明的是:對于面向開發者的產品來說,其用戶體驗中最重要的一環并不是什么主頁設計、登錄過程、或者SDK下載。這個產品的文檔包括一個很棒的《hybrid guide and reference》,以及一套開發教程。
開發者痛恨點擊鼠標,這已經不是什么秘密了。
6. 包含適當的快速指南
在這個方面的一個優秀范例是ckbone.js documentation,只要你有個鼠標,一切盡在把握。沒有哪個開發者會訴苦你舉例太多的。好的文檔應該是一整套有機的系統內容,能指引用戶通過文檔與API進行交互。退一萬步說,你至少讓你的文檔包含以下幾個部門。
7. 不要在例子中包含抽象概念
另外一個此方面優秀的范例是Stripe’s API(http://www.stripe.com) 。
開發指南:這是介于參考索引和開發教程中間程度的文檔。
8. 毫不吝惜使用層次
那么,什么才是制作優秀API文檔的樞紐因素呢?
我見過很多類似的情況,一個項目被草率地扔到GitHub的頁面上,僅僅配有兩行的readme說明文件。
我們非常贊成使用“單頁面大指南”的組織形式(鏈接),這種形式不僅能讓用戶縱覽全局,僅僅通過一個導航欄就能進入他們感愛好的任意主題,另外還有一個好處是:用戶在進行搜索的時候,僅僅搜索當前頁面,就能涵蓋查找所有的內容。假如可能的話,為你的API提供各種編程語言版本的樣例程序,只要的API支持這些語言。
新聞標題:編寫優質的API文檔的方法,怎么進行API文檔的編寫,API文檔優質的編寫方法
文章網址:http://m.newbst.com/news9/166209.html
成都網站建設公司_創新互聯,為您提供域名注冊、網頁設計公司、手機網站建設、動態網站、建站公司、定制開發
聲明:本網站發布的內容(圖片、視頻和文字)以用戶投稿、用戶轉載內容為主,如果涉及侵權請盡快告知,我們將會在第一時間刪除。文章觀點不代表本網站立場,如需處理請聯系客服。電話:028-86922220;郵箱:631063699@qq.com。內容未經允許不得轉載,或轉載時需注明來源: 創新互聯
猜你還喜歡下面的內容