網(wǎng)站建設(shè)軟件擁有一份優(yōu)質(zhì)的技術(shù)文檔是決定你的項(xiàng)目是否引人關(guān)注的重要因素。無論開源產(chǎn)品或面向開發(fā)者的產(chǎn)品，均是如此。你的設(shè)計(jì)文檔不應(yīng)當(dāng)僅僅直白地列出所有的終端函數(shù)和其參數(shù)。好的文檔應(yīng)該是一整套有機(jī)的系統(tǒng)內(nèi)容，能指引用戶通過文檔與API進(jìn)行交互。你至少讓你的文檔包含以下幾個(gè)部分。參考索引、開發(fā)指南、開發(fā)教程。
1.加入人性化的因素
閱讀技術(shù)文檔枯燥乏味，自然不像坐過山車那樣緊張刺激。不過，你至少可以通過加入一些人性化的因素，或者開開玩笑。給你的例子中的變量其一些好玩兒的名字吧，別老是把函數(shù)名稱叫什么foo之類的，好讓你的讀者有煥然一新的感覺。至少，這可以保證你的讀者不會(huì)讀著讀著就睡過去。
3.減少點(diǎn)擊次數(shù)
開發(fā)者痛恨點(diǎn)擊鼠標(biāo)，這已經(jīng)不是什么秘密了。千萬別把你的文檔分散在數(shù)以萬計(jì)的頁面當(dāng)中。盡量把相關(guān)的主題都放到一個(gè)頁面里。我們非常贊成使用“單頁面大指南”的組織形式（鏈接），這種形式不僅能讓用戶縱覽全局，僅僅通過一個(gè)導(dǎo)航欄就能進(jìn)入他們感興趣的任意主題，另外還有一個(gè)好處是：用戶在進(jìn)行搜索的時(shí)候，僅僅搜索當(dāng)前頁面，就能涵蓋查找所有的內(nèi)容。
4.不要在例子中包含抽象概念
你可以爭辯說，我的API本身就是個(gè)抽象體，抽象就是它的特點(diǎn)。然而，當(dāng)你在教會(huì)開發(fā)者如何使用的過程中，還是能不抽象就不抽象比較好。在你的文檔中盡可能地舉現(xiàn)實(shí)中的例子吧。沒有哪個(gè)開發(fā)者會(huì)抱怨你舉例太多的。實(shí)際上，這種做法能顯著地縮短開發(fā)者理解你產(chǎn)品的時(shí)間。對(duì)此，我們的網(wǎng)站里甚至給出一個(gè)代碼樣例加以解釋。
5.支持多種編程語言
我們生活在一個(gè)多語言的世界。如果可能的話，為你的API提供各種編程語言版本的樣例程序，只要的API支持這些語言。多數(shù)時(shí)候，多語言的工作都是由客戶端庫來完成的。要知道，開發(fā)者要想掌握一套API，離開他們熟悉的編程語言，是很難想象的。MailGun’sAPI為此做出了良好的榜樣。它提供了curl，Ruby，Python，Java，C#和PHP等多個(gè)版本供開發(fā)者選擇。
6.包含適當(dāng)?shù)目焖僦改?/div>
萬事開頭難，開發(fā)者學(xué)習(xí)一套全新的API，不得不重新適應(yīng)其全新的思維方式，學(xué)習(xí)代價(jià)高昂。對(duì)于這個(gè)問題的解決辦法是：通過快速指南來引導(dǎo)開發(fā)者。快速指南的目的是讓用戶用小的代價(jià)學(xué)習(xí)如何利用你提供的API干一些小事。僅此而已。一旦用戶完成了快速指南，他們就對(duì)自己有了信心，并能向更加深入的主題邁進(jìn)。
7.提供樣例應(yīng)用
在學(xué)習(xí)結(jié)束的時(shí)候，開發(fā)者希望能看到關(guān)于項(xiàng)目產(chǎn)品應(yīng)用的大致藍(lán)圖。達(dá)到這一目的好的辦法，莫過于提供可運(yùn)行的樣例應(yīng)用。我發(fā)現(xiàn)，應(yīng)用程序代碼是將API運(yùn)行機(jī)理和系統(tǒng)整合融會(huì)貫通好的辦法。samplecodeinApple’siOSDeveloperLibrary則是這方面做得很好的，它包含了詳盡的iOS樣例程序，并按主題一一分類。
8.絕不放過任何邊界情況
使用API開發(fā)應(yīng)用，所能遭遇的糟糕的情況，莫過于你發(fā)現(xiàn)了一個(gè)文檔中沒有提到的錯(cuò)誤。如果你遇到這種情況，就意味著你不能確認(rèn)究竟是你的程序出了錯(cuò)，還是你對(duì)API的理解出了錯(cuò)。因此，參考索引中必須包含每種假設(shè)可能造成的邊界情況，不論是顯示的還是隱式的?；c(diǎn)兒時(shí)間在這個(gè)上面，絕對(duì)能起到事半功倍的效果。
如有意向，請(qǐng)聯(lián)系我們的客戶經(jīng)理
我們會(huì)根據(jù)您的需求為你制定詳細(xì)的解決方案
在線咨詢
or 撥打業(yè)務(wù)熱線：186-0984-0880
