本文主要內容：API文件提供了預測客戶成功的關鍵路徑；在程式碼附近的文件上進行協作可以更好地檢查程式碼和文件檔案，提高自動化效率，並專門針對文件進行質量測試；提供通用文件框架，標準，自動化和工具，以提高團隊效率。

編寫文件有時候會非常枯燥乏味，但優秀的文件是增加API被採用的一個很好的前提。編寫出色的文件與編寫程式碼一樣需要嚴謹。隨著API的質量逐漸成為產品增長的指標，您的文件比以往任何時候都更加重要，優秀的文件很大程度上代表建立了成功的API。API定義和文件常常結合在一起，雖然今天的API規範越來越多地作為GitHub中的程式碼進行管理，但API文件並非如此。所以需要讓我們對此進行更改，以便在GitHub和相關程式碼庫中編寫和管理API文件（包括相關網站）的標準。

通過儘可能靠近程式碼和API定義協作編寫文件，您可以自動執行文件測試，構建和部署。API的文件通常構建為網站，因此如果在分段構建期間就可以進行連結檢查等測試。這種方法提供了許多好處：經過測試的文件構建；支援連續釋出；支援對文件內容和程式碼的評論；多個輸出（包括經過測試的程式碼示例）；文件的釋出管理（如API的早期訪問版本）或增量更改和新增到釋出了API，並防止程式碼合併。

文件持續整合/交付

對於REST API文件，三個框架以網頁的形式提供文件輸出，其中許多是互動式的。這些是OpenAPI（Swagger），RESTful API建模語言（RAML）和API藍圖。OpenAPI（以前稱為Swagger）基於JSON輸出，由於YAML是JSON的超集，因此您可以交換描述API的原始檔。RAML是一種基於YAML的語言，用於描述REST API。API Blueprint使用Markdown，也可以遵循GitHub Flavored Markdown語法。

許多程式語言都有一個文件框架，可以很好地與程式碼本身整合。通常，這些是靜態站點生成器，例如Jekyll for Ruby和Sphinx for Python。文件的原始檔是Markdown或reStructured Text（RST）。使用這些靜態站點生成器，您可以建立漂亮的文件站點。事實上，GitHub上有一系列連結到漂亮的文件網站，其中包括Stripe API文件站點和Basho文件 - 這些是獲得美觀和實用程式最高分的示例API站點。

由於可以使用指令碼轉換這些文件原始檔和網站配置檔案，因此您可以使用與程式碼相同的構建作業來持續構建文件。通過從靜態目錄複製平面檔案來部署Jekyll站點，因此您可以儲存指令碼以使用其他構建檔案在程式碼儲存庫中構建站點。您還可以使用簡單的連結檢查程式在部署站點之前測試任何損壞的連結。HTMLProofer庫是一個為此而編寫的Ruby庫。

GitHub提供的部署機制稱為GitHub Pages。您可以選擇觸發文件網站部署。您可以從gh-pages分支，主分支自動化構建，或始終從主分支上的/ docs目錄部署文件。雖然您可以部署到自定義域名，但GitHub頁面的一個限制是您不能直接通過HTTPS提供服務，但作為免費服務，它是一個很好的起點。對於生產網站，您可以從GitHub部署到具有所需安全要求的雲伺服器或VPS。而GitHub Enterprise是GitHub的內部部署，用於內部部署，提供類似的託管站點功能。

為什麼要像程式碼一樣處理文件

當成果已經可以交付給開發人員時，那與開發人員一起寫文件會很有效。API文件任務為處理程式碼等文件的原因和時間提供了一個很好的示例。特別是在設計API或向API新增功能時的關鍵設計點，開發人員可以像文件程式碼一樣貢獻文件。

例如，在自動化參考資訊時，您可以獲得即時性和準確性，並通過在GitHub，Bitbucket或GitLab等社交編碼系統中協作編寫來獲得貢獻，質量和同理心。此外，API的最大成功指標之一是文件的準確性和有用性。當您的團隊處理程式碼等API文件時，以下是一些特定的好處，下面將對此進行更深入的探討：

1.協作效率

可以為開發人員和文章協作編寫者兩個角色提供有價值的資訊。開發人員希望為類似於自己的受眾撰寫文章，為讀者提供經驗分享。協作編寫者有一個特殊的訣竅來組織資訊，文筆更好，並以適當的順序揭示概念和參考資訊。如果在同一個儲存庫中協同工作可以提供溝通的效率，增加教學和被教學的機會。

2.貢獻收益

當沒有專門的技術寫作團隊時，你可以擴大貢獻者的數量，即使API本身不是公共文件的公共檔案。或者，您可以通過在GitHub或Bitbucket等版本控制系統中提供開源文件儲存庫，從終端使用者自己獲得更多貢獻。當文件與程式碼位於同一儲存庫中時，任何感興趣的開發人員（包括客戶）都可以訂閱拉取請求的通知。

3.跟蹤文件中的錯誤

要獲得更高質量的文件，請提供直接在輸出頁面上報告文件錯誤的方法。正如萊納斯定律所述，“給予足夠的眼球，所有的錯誤都是淺薄的”。通過為這些眼球提供報告錯誤的位置，您可以為文件提供更多類似程式碼的質量跟蹤。此外，通過問題跟蹤制定的指標，您可以衡量文件的質量，並確保在需要解決這些錯誤時可使用指標來判斷。

4.對文件和程式碼的評論

在檢視程式碼中包含的文件時，審閱者可以在文件不足時阻止對程式碼的更改。該審查指南為團隊提供了使文件具有高質量的能力，即使它們必須與快速變化的程式碼同步。

將文件原始檔放在像GitHub這樣的開放系統中可以使內容具有開放貢獻，類似於開原始碼。在OpenStack中，大量的開源雲專案，文件貢獻過程與程式碼貢獻過程相同。編寫者和開發人員在訪問僅文件儲存庫（僅程式碼儲存庫）時具有相同的協作工具和背景知識。

當您的API定義需要一定程度的守門或小心防護時，您還可以考慮將GitHub Enterprise用於內部API文件。您的團隊仍然可以在內部獲得協作優勢，而無需向全世界開啟您的文件和程式碼。

5.部署和釋出

處理程式碼等文件時，意識到您正在將構建與部署分離。通過這種方式，您可以對文件的早期草稿進行稽核，並且在文件構建部署併發布到網站之前，它都可以隨時進行修正。或者，您可以選擇不斷髮布一些文件以跟上程式碼。例如，您可以選擇編寫敘述性文件和教程，這些文件和教程會隨著每個補丁集新增而不斷髮布。但對於像OpenAPI規範這樣的合同文件，只有在考慮在特定版本下發布API時，才能部署新文件。

6.測試和構建文件

通過為評論提供匹配的分段構建和向讀者交付的生產構建，您可以確信您對構建的文件的稽核滿足使用者需求。請參閱以下部分中的示例。

docs的示例測試

您可以測試文件原始檔的質量以及是否構建。您還可以檢查拼寫或語法，但也可以通過人為進行檢查。但測試文件的目的是減輕人類審閱者的審查負擔，自動化能節省時間，以便可以編寫，釋出和釋出更多文件檔案。

1.連結檢查

對於許多靜態站點生成器，有專門用於檢查站點中所有連結的庫。例如，在檢查像docslikecode.com這樣的Jekyll網站上的連結時，Travis CI工作很簡單：

#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build
bundle exec htmlproofer ./_site

通過這種型別的測試，人工審閱者不必花時間點選新補丁中的每個連結。如果需要更新外部連結，那麼這個測試的結果會通知您。如果內部連結因修補程式本身而中斷，則系統可以在人為檢視修補程式之前修復它。

2.JSON格式

使用REST API文件，請求和響應通常是JSON檔案，對於閱讀文件的人在將自己的環境與文件進行比較時非常有價值。在讀者需要複製和貼上請求的情況下，正確格式化示例至關重要。在OpenStack中，我們有一組包含JSON測試器和格式化程式的通用文件工具。通過對傳入的修補程式對文件檔案執行此測試，讀者可以確定所包含的JSON檔案是否格式正確。此外，當它們可以在本地執行簡單命令以確保JSON格式正確時，它可以使貢獻者更容易建立補丁。

3.驗證的請求和響應

高階文件測試可以檢查文件中包含的示例請求和響應。用檢視程式碼檔案相同的方式檢視文件檔案時，準確性通常是最高值。因此，通過針對正常工作的API端點測試示例，您可以證明這些示例也適用於實際情況。這種型別的驗證提供了每次都可用的成功文件示例，因為只有它們通過驗證測試，它們才被髮布。

4.建立檢查

自動化文件測試可以節省讀者的時間，因為他們不必自己構建文件來檢視輸出。此外您可以測試損壞的連結或不正確格式化的JSON檔案的構建。對於任何奇怪的問題，檢視源文件和輸出文件都很有幫助。

結論

在與程式碼庫相同的倉庫中協同處理文件，可以更好地為客戶提供服務，無論他們是組織的內部還是外部。通過將API文件視為程式碼，您可以找到自動化途徑，提高效率，加快文件構建，在文件中構建成功示例。

&n