北京市網站建設企業酷站科技：撰寫技術資料，是令諸多
網站制作開發人員望而卻步的每日任務之一。它自身是一件耗時費力才可以搞好的工作中。但是大部分情況下，大家卻一直想抄抄近道，那樣做的結果通常十分感到遺憾的，由于高品質的技術資料是決策你的新項目是不是引人注意的關鍵要素。不管開源系統商品或朝向開發人員的商品，均是這般。
事實上，我覺得表明的是：針對朝向開發人員的商品而言，其客戶體驗中最重要的一環并不是什么首頁設計、登陸全過程、或是SDK免費下載。真實最重要的是商品的API文本文檔！假如沒有人了解你的商品怎么使用，縱然它惟妙惟肖，又有有什么用？
假如你是一個主要從事朝向開發人員設計產品的技術工程師，那麼撰寫健全的技術資料，就跟你為終端產品用戶出示優良客戶體驗一樣重要。
我見過很多相近的狀況，一個新項目被草率地丟到GitHub的網頁頁面上，只是裝有二行的readme表明文檔。要了解，真實取得成功的API文本文檔是必須用我們的愛細心制做的工藝品。在Parse商品新項目里，大家就把自己獻給了這門造型藝術！
那麼，哪些才算是制做出色API文本文檔的首要條件呢？
1. 決不吝嗇應用層級
你的設計文檔不理應只是直接地列舉全部的終端設備涵數和其主要參數。好的文本文檔應該是一整套有機化學的系統軟件內容，能引導客戶根據文本文檔與API開展互動。退一萬步說，你最少給你的文本文檔包括下列好多個一部分。
參照數據庫索引：參照數據庫索引理應是一個事無大小的目錄，包括了全部作用涵數的消極思想。它務必標明全部的基本數據類型和函數規格型號。高級開發人員要可以拿著它一天到晚當教材應用。
開發設計手冊：它是接近參照數據庫索引和開發設計實例教程正中間水平的文本文檔。它就好像是一篇更為詳盡的參照數據庫索引，表明了怎么使用各種各樣API。
開發設計實例教程：開發設計實例教程會更為實際地論述怎么使用API，并主要詳細介紹在其中的一部分作用。假如能出示可編譯程序運作的源碼，那么就最好不過了。
在Parse新項目里，大家保證了所述全部三個一部分。現階段大家已經勤奮定編大量的開發設計實例教程。
此外一個此層面出色的案例是Stripe’s API（http://www.stripe.com） 。這一商品的文本文檔包含一個非常好的《hybrid guide and reference》，及其一套開發設計實例教程。《GitHub API參考》也歷經了優良的設計方案。
你能爭論說，我的API自身便是個抽象性體， 抽象性便是它的特性。殊不知，如果你在教會開發人員怎么使用的全過程中，還是能不抽象性也不抽象性比較好。
在你的文本文檔中盡量地舉實際中的事例吧。沒有哪一個開發人員會埋怨你舉例說明過多的。事實上，這類作法能明顯地減少開發人員了解你商品的時間。對于此事，大家的網址里乃至得出一個編碼示例多方面表述。
2. 降低點一下頻次
開發人員討厭點擊鼠標，這早已并不是什么秘密了。千萬不要將你的文本文檔分散化在不計其數的網頁頁面之中。盡可能把有關的主題風格都放進一個網頁頁面里。
大家十分贊同應用“單網頁頁面大手冊”的組織結構（連接），這類方式不但能讓客戶縱觀全局性，只是根據一個導航條就能進到她們很感興趣的隨意主題風格，此外還有一個益處是：客戶在開展檢索的情況下，只是檢索當今網頁頁面，就能包含搜索全部的內容。
在這個層面的一個出色案例是ckbone.js documentation，如果你有一個電腦鼠標，一切了如指掌。
開頭難，開發人員學習培訓一套全新升級的API，迫不得已再次融入其全新升級的思維模式，學習培訓成本昂貴。針對這個問題的解決方案是：根據迅速手冊來正確引導開發人員。
迅速手冊的目地是讓客戶用最少的成本學習培訓怎樣運用你出示的API干一些瑣事。我不相信愛情。一旦客戶完成了迅速手冊，她們就對自身擁有自信心，能夠向更為深層次的主題風格邁入。
舉個事例，大家的迅速手冊能讓客戶免費下載SDK及其在服務平臺上儲存一個目標。因此，大家乃至干了一個按鍵，來讓客戶檢測她們是不是恰當地完成了迅速手冊。這能提高客戶的自信心，以激勵她們學習培訓大家商品別的的一部分。
3. 適用多種多樣計算機語言
大家日常生活在一個多語言的全球。假如很有可能得話，給你的API出示各種各樣計算機語言版本號的示例程序流程，要是的API適用這種語言。大部分情況下，多語言的工作中全是由手機客戶端庫來進行的。要了解，開發人員要想把握一套API，離去她們了解的計算機語言，是難以想像的。
MailGun’s API因此作出了優良的楷模。它出示了curl，Ruby，Python，Java，C#和PHP等好幾個版本號供開發人員挑選。
4. 絕不放過一切界限狀況
應用API開發設計運用，能夠遭受的最槽糕的狀況，莫過你發覺了一個文本文檔中沒有提及的不正確。假如你碰到這類狀況，就代表著你不能確定到底就是你的程序流程出了錯，還是你對API的了解出了錯。
因而，參照數據庫索引中務必包括每個假定很有可能導致的界限狀況，無論是顯示信息的還是隱式的。花一點兒時間在這個上邊，肯定能具有事倍功半的實際效果。
在學習培訓完畢的情況下，開發人員期待能見到有關新項目商品運用的大概宏偉藍圖。做到這一目地最好是的方法，莫過出示可運作的示例運用。我發現了，運用編程代碼是將API運作原理和系統軟件融合融匯貫通最好是的方法。
sample code in Apple’s iOS Developer Library 則是這些方面做得非常好的，它包括了詳細的iOS示例程序流程，并按主題風格一一歸類。
5. 添加個性化的要素
閱讀文章技術資料枯燥無味，當然不象坐過山車那般焦慮不安刺激性。但是，你最少能夠 根據添加一些個性化的要素，或是開玩笑。讓你的事例中的自變量其一些好玩的名字吧，別老是把涵數名字叫什么名字foo這類的，好給你的閱讀者有煥然一新的覺得。
最少，這能夠 確保你的閱讀者不容易讀著讀著就睡下去。
文中公布于
北京市網站制作企業酷站科技
http://www.ttscar.com.cn">來源于申明：以上內容一部分(包括照片、文本)來自互聯網，若有侵權行為，請立即與本網站聯絡（010-57218159）。
如沒特殊注明，文章均為酷站科技原創,轉載請注明來自http://www.ttscar.com.cn/jianzhanzhishi/3956.html
服務熱線
18911184380
