更新時間：2025-09-15 13:56:53
網站建設
590北京網站建設公司推來客：編寫技術文檔是許多網站制作開發人員最頭疼的工作之一。做好這件事本身就是一件費時費力的工作。但是很多時候，人們總是想抄捷徑，而這樣做的結果往往是非常令人遺憾的，因為高質量的技術文檔是決定你的項目是否受到關注的重要因素。對于開源產品和面向開發人員的產品都是如此。
其實我想說的是，面向開發者的產品，最重要的用戶體驗不是首頁設計、登錄流程、SDK下載。最重要的是產品的API文檔！如果沒有人知道如何使用它，即使它工作出色，你的產品又有什么用呢？
如果您是專門為開發人員設計產品的工程師，那么編寫完善的技術文檔與為最終用戶提供良好的用戶體驗一樣重要。
我見過很多類似的情況，一個項目被粗心地扔到GitHub 頁面上，除了兩行自述文件外什么都沒有。要知道，真正成功的API 文檔是一件用愛精心打造的藝術品。在Parse 產品項目中，我們致力于這門藝術！
那么，好的API 文檔的關鍵要素是什么？
1. 千萬不要在層次上吝嗇
您的設計文檔不應只是簡單地列出所有終端功能及其參數。一個好的文檔應該是一套有機的系統內容，能夠引導用戶通過文檔與API進行交互。退一步說，你至少應該讓你的文檔包含以下部分。
參考索引：參考索引應該是一個詳細的列表，包括所有功能的繁文縟節。它必須注釋所有數據類型和函數規范。高級開發人員應該可以整天拿著它，把它當作參考書來使用。
開發指南：這是介于參考索引和開發教程之間的文檔。它就像一份更詳細的參考資料，解釋了如何使用各種API。
開發教程：開發教程會更具體地講解API的使用方法，重點介紹其部分功能。如果能提供可以編譯運行的源碼就更好了。
在Parse 項目中，我們執行上述所有三個操作。我們目前正在努力編寫更多的開發教程。
另一個很好的例子是Stripe 的API (http://www.stripe.com)。該產品的文檔包括一個很棒的《hybrid guide and reference》 和一組開發教程。《GitHub API參考》也設計的不錯。
你可以說我的API本身就是一種抽象，抽象就是它的特點。但是，當你在教開發人員如何使用它時，最好不要抽象或不抽象。
在您的文檔中盡可能使用真實示例。沒有開發人員會抱怨你舉了太多的例子。事實上，這樣做可以顯著減少開發人員了解您的產品所需的時間。我們的網站上什至有一個代碼示例來解釋這一點。
2. 更少的點擊
開發人員討厭點擊鼠標已經不是什么秘密了。切勿將您的文檔分散在數萬頁上。嘗試將相關主題放在一頁中。
我們非常贊成使用“一頁指南”的組織形式（鏈接）。這種形式不僅可以讓用戶縱覽全局，還可以通過一個導航欄進入任何他們感興趣的話題。另一個好處是，用戶在搜索時，只要搜索當前頁面，就可以找到所有的內容。
一個很好的例子就是ckbone.js 文檔，只要你有鼠標，一切都在控制之中。
萬事開頭難。開發人員學習一組新的API，必須重新適應他們的新思維方式。學習成本很高。這個問題的解決方案是通過快速指南來指導開發人員。
快速指南的目的是讓用戶學習如何使用您提供的API 以最小的努力做一些小事情。就這樣。用戶完成快速指南后，他們就會對自己充滿信心，并可以繼續討論更深入的主題。
例如，我們的快速指南允許用戶下載SDK 并將對象存儲在平臺上。為此，我們甚至制作了一個按鈕，讓用戶測試他們是否正確完成了快速指南。這會增強用戶信心并鼓勵他們了解我們產品的其他部分。
3.支持多種編程語言
我們生活在一個多語言的世界。如果可能，請以各種編程語言為您的API 提供示例程序，只要您的API 支持這些語言。大多數時候，多語言工作是由客戶端庫完成的。要知道，開發者要想掌握一套API，離開自己熟悉的編程語言是很難想象的。
MailGun 的API 就是一個很好的例子。它提供了curl、Ruby、Python、Java、C#和PHP多個版本供開發者選擇。
4. 永遠不要放過任何邊緣情況
使用API 開發應用程序最糟糕的事情是發現文檔中未提及的錯誤。如果遇到這種情況，說明你無法確認是你的程序有問題，還是你對API的理解有誤。
因此，每
種假設可能造成的邊界情況，不論是顯示的還是隱式的。花點兒時間在這個上面，絕對能起到事半功倍的效果。在學習結束的時候，開發者希望能看到關于項目產品應用的大致藍圖。達到這一目的最好的辦法，莫過于提供可運行的樣例應用。我發現，應用程序代碼是將API運行機理和系統整合融會貫通最好的辦法。
sample code in Apple’s iOS Developer Library 則是這方面做得很好的，它包含了詳盡的iOS樣例程序，并按主題一一分類。
5. 加入人性化的因素
閱讀技術文檔枯燥乏味，自然不像坐過山車那樣緊張刺激。不過，你至少可以通過加入一些人性化的因素，或者開開玩笑。給你的例子中的變量其一些好玩兒的名字吧，別老是把函數名稱叫什么foo之類的，好讓你的讀者有煥然一新的感覺。
至少，這可以保證你的讀者不會讀著讀著就睡過去。
本文發布于北京網站制作公司推來客http://www.tlkjt.com/
我們專注高端建站，小程序開發、軟件系統定制開發、BUG修復、物聯網開發、各類API接口對接開發等。十余年開發經驗，每一個項目承諾做到滿意為止，多一次對比，一定讓您多一份收獲！
