編寫技術文件，是令眾多開發者望而生畏的任務之一。它本身是一件費時費力才能做好的工作。可是大多數時候，人們卻總是想抄抄捷徑，這樣做的結果往往非常令人遺憾的，因為優質的技術文件是決定你的專案是否引人關注的重要因素。無論開源產品或面向開發者的產品，均是如此。
實際上，我想說明的是：對於面向開發者的產品來說，其使用者體驗中最重要的一環並不是什麼主頁設計、登入過程、或者SDK下載。真正最重要的是產品的API文件！如果沒人知道你的產品如何使用，縱使它巧奪天工，又有何用？
如果你是一個專門從事面向開發者產品設計的工程師，那麼編寫完善的技術文件，就跟你為終端使用者提供良好使用者體驗一樣關鍵。（API 設計是很聰明的投資，你得到的回報是忠實的開發人員。詳見：《為什麼“開發人員友好性”是API設計的核心》。）
我見過許多類似的情況，一個專案被草率地扔到GitHub的頁面上，僅僅配有兩行的readme說明檔案。要知道，真正成功的API文件是需要用愛來悉心製作的藝術品。在Parse產品專案裡，我們就把自己奉獻給了這門藝術！
那麼，什麼才是製作優秀API文件的關鍵因素呢？
0. 絕不吝惜使用層次
你的設計文件不應當僅僅直白地列出所有的終端函式和其引數。好的文件應該是一整套有機的系統內容，能指引使用者通過文件與API進行互動。退一萬步說，你至少讓你的文件包含以下幾個部分。
參考索引：參考索引應當是一個事無鉅細的列表，包含了所有功能函式的繁文縟節。它必須註明所有的資料型別和函式規格。高階開發者要能夠拿著它整天當參考書使用。
開發指南：這是介於參考索引和開發教程中間程度的文件。它就彷彿是一篇更加詳細的參考索引，闡明瞭如何使用各種API。
開發教程：開發教程會更加具體地闡述如何使用API，並著重介紹其中的一部分功能。如果能提供可編譯執行的原始碼，那就再好不過了。
在Parse專案裡，我們做到了上述所有三個部分。目前我們正在努力編制更多的開發教程。
另外一個此方面優秀的範例是Stripe’s API(http://www.stripe.com) 。這個產品的文件包括一個很棒的《hybrid guide and reference》，以及一套開發教程。《GitHub API參考》也經過了良好的設計。
1. 不要在例子中包含抽象概念
你可以爭辯說，我的API本身就是個抽象體, 抽象就是它的特點。然而，當你在教會開發者如何使用的過程中，還是能不抽象就不抽象比較好。
在你的文件中儘可能地舉現實中的例子吧。沒有哪個開發者會抱怨你舉例太多的。實際上，這種做法能顯著地縮短開發者理解你產品的時間。對此，我們的網站裡甚至給出一個程式碼樣例加以解釋。
2. 減少點選次數
開發者痛恨點選滑鼠，這已經不是什麼祕密了。千萬別把你的文件分散在數以萬計的頁面當中。儘量把相關的主題都放到一個頁面裡。
我們非常贊成使用“單頁面大指南”的組織形式（連結），這種形式不僅能讓使用者縱覽全域性，僅僅通過一個導航欄就能進入他們感興趣的任意主題，另外還有一個好處是：使用者在進行搜尋的時候，僅僅搜尋當前頁面，就能涵蓋查詢所有的內容。
在這個方面的一個優秀範例是ckbone.js documentation，只要你有個滑鼠，一切盡在掌握。
3. 包含適當的快速指南
萬事開頭難，開發者/程式設計師學習一套全新的API，不得不重新適應其全新的思維方式，學習代價高昂。對於這個問題的解決辦法是：通過快速指南來引導開發者。
快速指南的目的是讓使用者用最小的代價學習如何利用你提供的API幹一些小事。僅此而已。一旦使用者完成了快速指南，他們就對自己有了信心，並能向更加深入的主題邁進。
舉個例子，我們的快速指南能讓使用者下載SDK以及在平臺上儲存一個物件。為此，我們甚至做了一個按鈕，來讓使用者測試他們是否正確地完成了快速指南。這能提升使用者的信心，以鼓勵他們學習我們產品其他的部分。
4. 支援多種程式語言
我們生活在一個多語言的世界。如果可能的話，為你的API提供各種程式語言版本的樣例程式，只要的API支援這些語言。多數時候，多語言的工作都是由客戶端庫來完成的。要知道，開發者要想掌握一套API，離開他們熟悉的程式語言，是很難想象的。
MailGun’s API為此做出了良好的榜樣。它提供了curl、Ruby、Python、Java、C# 和 PHP 等多個版本供開發者選擇。
5. 絕不放過任何邊界情況
使用API開發應用，所能遭遇的最糟糕的情況，莫過於你發現了一個文件中沒有提到的錯誤。如果你遇到這種情況，就意味著你不能確認究竟是你的程式出了錯，還是你對API的理解出了錯。
因此，參考索引中必須包含每種假設可能造成的邊界情況，不論是顯示的還是隱式的。花點兒時間在這個上面，絕對能起到事半功倍的效果。
6. 提供樣例應用
在學習結束的時候，開發者希望能看到關於專案產品應用的大致藍圖。達到這一目的最好的辦法，莫過於提供可執行的樣例應用。我發現，應用程式程式碼是將API執行機理和系統整合融會貫通最好的辦法。
sample code in Apple’s iOS Developer Library 則是這方面做得很好的，它包含了詳盡的iOS樣例程式，並按主題一一分類。
7. 加入人性化的因素
閱讀技術文件枯燥乏味，自然不像坐雲霄飛車那樣緊張刺激。不過，你至少可以通過加入一些人性化的因素，或者開開玩笑。給你的例子中的變數其一些好玩兒的名字吧，別老是把函式名稱叫什麼foo之類的，好讓你的讀者有煥然一新的感覺。
至少，這可以保證你的讀者不會讀著讀著就睡過去。
結論：
若要想深入人心，一個良好的設計文件必不可少。然而，設計一個好文件是需要大量投入才能形成的。但是，這些投入是值得的，因為它的意義和產品本身同等重要。
編寫良好文件的另一半訣竅，是要從產品開發的初始階段就朝著這個方向努力。不過，這就不是本文討論的範疇了。
補充資料：《如何設計出色的API？為什麼 API 很重要？| How to Design a Good API and Why it Matters 》作者：Joshua J. Bloch（Google 首席 Java 架構師，著有《Effective Java》） ，49頁的文件。演講視訊：連結。
打賞支援我翻譯更多好文章，謝謝！
打賞譯者
打賞支援我翻譯更多好文章，謝謝！
