北京網站建設公司商企云：編寫技術文檔，是令眾多網站制作開發(fā)者望而生畏的任務之一。它本身是一件費時費力才能做好的工作?？墒谴蠖鄶禃r候，人們卻總是想抄抄捷徑，這樣做的結果往往非常令人遺憾的，因為優(yōu)質的技術文檔是決定你的項目是否引人關注的重要因素。無論開源產品或面向開發(fā)者的產品，均是如此。實際上，我想說明的是：對于面向開發(fā)者的產品來說，其用戶體驗中最重要的一環(huán)并不是什么主頁設計、登錄過程、或者SDK下載。真正最重要的是產品的API文檔！如果沒人知道你的產品如何使用，縱使它巧奪天工，又有何用？如果你是一個專門從事面向開發(fā)者產品設計的工程師，那么編寫完善的技術文檔，就跟你為終端用戶提供良好用戶體驗一樣關鍵。我見過許多類似的情況，一個項目被草率地扔到GitHub的頁面上，僅僅配有兩行的readme說明文件。要知道，真正成功的API文檔是需要用愛來悉心制作的藝術品。在Parse產品項目里，我們就把自己奉獻給了這門藝術！那么，什么才是制作優(yōu)秀API文檔的關鍵因素呢？1. 絕不吝惜使用層次你的設計文檔不應當僅僅直白地列出所有的終端函數和其參數。好的文檔應該是一整套有機的系統(tǒng)內容，能指引用戶通過文檔與API進行交互。退一萬步說，你至少讓你的文檔包含以下幾個部分。參考索引：參考索引應當是一個事無巨細的列表，包含了所有功能函數的繁文縟節(jié)。它必須注明所有的數據類型和函數規(guī)格。高級開發(fā)者要能夠拿著它整天當參考書使用。開發(fā)指南：這是介于參考索引和開發(fā)教程中間程度的文檔。它就仿佛是一篇更加詳細的參考索引，闡明了如何使用各種API。開發(fā)教程：開發(fā)教程會更加具體地闡述如何使用API，并著重介紹其中的一部分功能。如果能提供可編譯運行的源代碼，那就再好不過了。在Parse項目里，我們做到了上述所有三個部分。目前我們正在努力編制更多的開發(fā)教程。另外一個此方面優(yōu)秀的范例是Stripe’s API（http://www.stripe.com） 。這個產品的文檔包括一個很棒的《hybrid guide and reference》，以及一套開發(fā)教程?！禛itHub API參考》也經過了良好的設計。你可以爭辯說，我的API本身就是個抽象體， 抽象就是它的特點。然而，當你在教會開發(fā)者如何使用的過程中，還是能不抽象就不抽象比較好。在你的文檔中盡可能地舉現實中的例子吧。沒有哪個開發(fā)者會抱怨你舉例太多的。實際上，這種做法能顯著地縮短開發(fā)者理解你產品的時間。對此，我們的網站里甚至給出一個代碼樣例加以解釋。2. 減少點擊次數開發(fā)者痛恨點擊鼠標，這已經不是什么秘密了。千萬別把你的文檔分散在數以萬計的頁面當中。盡量把相關的主題都放到一個頁面里。我們非常贊成使用“單頁面大指南”的組織形式（鏈接），這種形式不僅能讓用戶縱覽全局，僅僅通過一個導航欄就能進入他們感興趣的任意主題，另外還有一個好處是：用戶在進行搜索的時候，僅僅搜索當前頁面，就能涵蓋查找所有的內容。在這個方面的一個優(yōu)秀范例是ckbone.js documentation，只要你有個鼠標，一切盡在掌握。萬事開頭難，開發(fā)者學習一套全新的API，不得不重新適應其全新的思維方式，學習代價高昂。對于這個問題的解決辦法是：通過快速指南來引導開發(fā)者?？焖僦改系哪康氖亲層脩粲米钚〉拇鷥r學習如何利用你提供的API干一些小事。僅此而已。一旦用戶完成了快速指南，他們就對自己有了信心，并能向更加深入的主題邁進。舉個例子，我們的快速指南能讓用戶下載SDK以及在平臺上存儲一個對象。為此，我們甚至做了一個按鈕，來讓用戶測試他們是否正確地完成了快速指南。這能提升用戶的信心，以鼓勵他們學習我們產品其他的部分。3. 支持多種編程語言我們生活在一個多語言的世界。如果可能的話，為你的API提供各種編程語言版本的樣例程序，只要的API支持這些語言。多數時候，多語言的工作都是由客戶端庫來完成的。要知道，開發(fā)者要想掌握一套API，離開他們熟悉的編程語言，是很難想象的。MailGun’s API為此做出了良好的榜樣。它提供了curl，Ruby，Python，Java，C#和PHP等多個版本供開發(fā)者選擇。4. 絕不放過任何邊界情況使用API開發(fā)應用，所能遭遇的最糟糕的情況，莫過于你發(fā)現了一個文檔中沒有提到的錯誤。如果你遇到這種情況，就意味著你不能確認究竟是你的程序出了錯，還是你對API的理解出了錯。因此，參考索引中必須包含每種假設可能造成的邊界情況，不論是顯示的還是隱式的。花點兒時間在這個上面，絕對能起到事半功倍的效果。在學習結束的時候，開發(fā)者希望能看到關于項目產品應用的大致藍圖。達到這一目的最好的辦法，莫過于提供可運行的樣例應用。我發(fā)現，應用程序代碼是將API運行機理和系統(tǒng)整合融會貫通最好的辦法。sample code in Apple’s iOS Developer Library 則是這方面做得很好的，它包含了詳盡的iOS樣例程序，并按主題一一分類。5. 加入人性化的因素閱讀技術文檔枯燥乏味，自然不像坐過山車那樣緊張刺激。不過，你至少可以通過加入一些人性化的因素，或者開開玩笑。給你的例子中的變量其一些好玩兒的名字吧，別老是把函數名稱叫什么foo之類的，好讓你的讀者有煥然一新的感覺。至少，這可以保證你的讀者不會讀著讀著就睡過去。本文發(fā)布于北京網站制作公司商企云http://m.2182725.com/