Github 是如何用 Github 撰寫 Github 文檔的

原文：https://github.com/blog/1939-...
譯者：@公子

---

一份好的文檔可以幫助人們理解，使用以及貢獻代碼到你的項目中，但這只是一個生成文檔的方程式的一半。生成文檔的底層系統使得人們，不管是你仍是一塊和你工做的團隊，撰寫文檔變得更加容易。

撰寫文檔最難的一部分既不是編寫配置工具，也不是說明項目應該如何搭建和升級，而應該是文檔的遣詞造句。Github 文檔團隊的成員大多都是有使用XML文檔生成工具和複雜的CMS系統背景的。正由於他們飽受了這些工具的折磨，因此爲了避免再使用這些工具咱們花費了大量的時間去思考咱們本身的文檔生成流程和設置。

咱們以前已經討論過咱們如何使用 Github 創建 Github 了。在這裏咱們將着重討論一下咱們如何使用 Github Page 服務運行 Github 幫助文檔 （目前每個月有上百萬的訪問量）的。

咱們之前的流程

幾個月前，咱們把幫助文檔的地層從 Rails 程序遷移到 Jekyll 託管在了 Github Pages 上。以前咱們的幫助文檔須要兩個相互獨立的項目倉庫：

• 用於託管維護網站、管理網站所用資源和文檔搜索加強的 Rails 應用程序
• 用戶託管由一大堆 Markdown 文件組成的網站具體內容

咱們的 Rails 應用程序託管在一個第三方平臺上。隨着對代碼的日益升級，咱們將它部署在了 Hubot ，這些都是咱們在維護 Github 主站的閒暇之餘完成的。（譯者注：Hubot 是 Github 開源的一款自動化智能化執行命令的機器人項目，具體刻參考 Hubot 的主頁。）

咱們正常的撰寫流程多是這個樣子的：

1. 當有新特徵開發出來的時候文檔團隊首先編寫好文檔內容
2. 建立一個新的 issue 去追蹤這個特徵
3. 當文檔更新完畢一切就緒以後，咱們會發起一個 pull request 去迭代更新文檔內容。
4. PR 發起成功後，咱們會使用 @ 方式提醒團隊（好比 @github/docs ）並會讓隊友們審查一下咱們的內容。
5. 當這個特徵開發完畢已經上線的時候，咱們會合並以前建立的 PR。 使用 webhook 可以幫助咱們在 內容倉庫 快速激活咱們部署的 Rails 應用程序。webhook 承擔了負責更新數據庫的任務。

下面是一個簡單的示例給咱們展現了一下咱們正常的工做流程：

使用 PR 進行工做是很是神奇的，由於它正好和咱們在團隊中使用的 Github 工做流程是一致的。而且咱們喜歡用 Markdown 語言書寫，更由於 Markdown 的語法能讓咱們不用花費多少時間就有效的描述新特徵的全部內容。

然而，咱們的 Rails 加強程序安裝設置起來卻很是的麻煩：

• 因爲咱們依賴外部主機，因此咱們須要專門的員工在咱們的工程，運維和安全團隊中監控站點和他們發起的響應事件。
• 咱們的文檔團隊並不能方便的在本地觀察內容的變化。雖然咱們使用的是 Markdown 編寫的內容，能夠實時預覽，可是咱們能忍須要配置一個本地的 Rails 應用服務去運行腳本將內容導入到數據庫中而後觀察其在網站上的最終效果。
• 雖然咱們不斷的調整 Rails 的服務器，可是咱們注意到用戶的請求依舊使得網站訪問變得很是緩慢。因爲 HTML 頁面是動態生成的，這就須要對數據庫進行請求，這就耗費了不少時間。爲了加快訪問速度，咱們還須要找尋更強大的緩存策略。

咱們知道咱們是時候作出改變作的更好了。

咱們的新流程

當 Jekyll 2.0 發佈的時候，咱們看到了曙光，是時候該把咱們這套該死的流程換成純靜態站了！特別是新增長的 Collections 文檔類型能讓你定義你須要的文件結構。另外，Jekyll 2.0 還增長了 Sass 和 CoffeeScript 的支持，這將使得編寫前端代碼變的更爲簡單便捷。

開源的好處在於它是開放的。咱們遷移到 Jekyll 後，咱們也向 Jekyll 發起了不少 PR 使得它能更好的服務 Github Pages 的用戶。

使用了 Jekyll 以後，咱們的工做流程發生了小小的變化。咱們仍然使用 Markdown 而且咱們仍然須要將內容 PR 到倉庫以便其它人審查。可是當咱們發起的 PR 被合併以後，Github Pages 網站將會在幾秒內自動快速建立並部署。

下面是咱們就如何使用 Jekyll 的核心功能以及咱們使用的一些強化 Github 幫助文檔站點的插件列了一個簡單的綱要。

咱們使用的 Gems

咱們儘量的依賴 Jekyll 代碼自己的功能去儘量減少咱們依賴本身維護的自定義插件，這樣能夠減小咱們的額外壓力。

Jekyll 2.0 內自帶的新的插件 Converter 使得用戶能夠將任何 標記語言書寫的文件轉換成 HTML。這樣用戶能夠隨便創做它的內容，Jekyll 只負責運行最後生成的 HTML文件就行了。舉個例子，只要你會，你甚至可使用 AsciiDoc 語法書寫你的內容。

最後，咱們開發了 jekyll-html-pipeline 插件，是咱們以前開源的 html-pipeline 在 Jekyll 上的加強版。這個確保了咱們的幫助站點的內容在 Github 上的任何地方看起來都是同樣的。咱們同時也開發了咱們本身的 Markdown filter 插件去提供一些語法擴展使得咱們編寫文檔更方便。

搜索

老流程的 Rails 網站中，咱們使用了 ElasticSearch 對咱們的數據庫進行索引並加強了 Github 幫助文檔的搜索系統。

如今，咱們使用 lunr-js 提供一個更快速的客戶端搜索體驗。固然咱們也經過篩選分析發現絕大多數用戶都會依賴外部的搜索服務進入咱們的文檔。因此，在新流程遷移完成以後，維護一個服務端的搜索引擎的解決方案看起來已經沒有多大的意義了。

內容引用

文檔團隊但願在編寫文檔的時候使用「內容引用」。內容引用容許你書寫一次某大段文字而後在網站的任何地方直接複用它。（這個靈感來自於 the DITA standard。 ）

舊的 Rails 系統並不能容許咱們書寫可複用的內容，可是如今咱們有了強大的 Jekyll，它支持用戶自定義 data files 。舉個例子，咱們已經建立了一個叫作conrefs.yml的文件，而且咱們有一系列字符串形式的鍵值對集合像以下這樣：

repositories:
    create_new:
        1. In the upper-right corner of any page, click {{ octicon-plus Plus symbol }}, and then click **New repository**.
           ![New repository menu](/assets/images/help/repository/repo-create.png)

此時咱們的鍵爲 repositories.create_new，其對應的值爲下方的 Markdown 源代碼（及 "In the upper-right corner..."）。咱們如今只須要簡單一步就能在多個頁面內容中複用這段內容：

To start the process:

{{ site.data.conrefs.repositories.create_new }}
2. Do something else.
3. You're done!

隨着 Github UI 的變化，咱們也許須要修改圖片或者從新定義某些地方的指向。這個時候，咱們僅僅只須要修改一個地方就能完成咱們的變化，比起之前須要修改全部的地方簡直不知道方便了多少倍。

版本化顯示文檔

另外一個隨着這次變化帶來的好處就是咱們如今可以顯示多版本的幫助文檔。隨着 Github 企業版 2.0.0 的發佈，咱們對以前的 11.10.3 版本 和如今的 2.0 版本這兩個不一樣版本提供了不一樣的幫助文檔內容。爲了達到這個目的，咱們在 Jekyll 站點內容使用了一個特別的 audience 變量，並在咱們的 Pages 倉庫生成 HTML 的時候檢查這個變量。

例如，在咱們的 config.yml 文件中，咱們設置了一個鍵叫作 audience 其值爲 11.10.340。若是某個特徵存在在新版本的 2.0 中可是不存在於老版本的 11.10.340 中，咱們會使用以下語法標記上這一部分：

{% if site.audience != '11.10.340' %}
 
This new feature...

{% endif %}

固然更使咱們高興的是，以上的實現都是基於 Jekyll 的核心功能，咱們不須要爲此建立或者維護任何其它的東西。

測試咱們的站點

靜態站點並不意味着咱們能夠不爲它開發測試驅動。

咱們的第一個測試內容的工具是 html-proofer。這個工具經過測試咱們網站的每個 URL 幫助咱們覈實咱們的連接和圖片都是正常的。

Ruby 的使用者們更熟悉使用 Capybara 在他們的測試中模擬網站的交互。在咱們的靜態站點實現一個相似的工具這個主意看起來很瘋狂？並不！ Github 的 bkeepers 4年前的一篇文章 已經談論過這個問題了。當時，咱們建立了更強大的測試工具，它涵蓋了咱們的內容測試和網站行爲測試。舉個例子來講，咱們經過檢查 YAML 文件中的鍵是否存在來確認某個內容引用是否有效，又或者說咱們會測試咱們的 JavaScript 代碼是否運行良好。

咱們的幫助文檔在 CI（譯者注：持續集成系統）上運行，這樣確保了用戶不會拿到損壞的內容。

速度

正如咱們以前提到的，新的流程使得咱們的 Pages 服務比以前使用 Rails 系統的時候有了標誌性的加快。這其中一部分緣由固然是由於新站點是一堆靜態的 HTML 文件的集成——咱們不須要向數據庫獲取任何內容。更值得注意的是，咱們花費了大量的時間配置咱們的 Pages 服務使得任何人運行它都是同樣的快速。咱們有的好處，好比使用 CDN 分佈式部署站點資源等，這些對每個 Github 用戶來講也一樣是可用的。

讓 Github Pages 爲你工做

文檔團隊經過 Github 利用 Github 的工做流程（譯者注：即前文提到的 Markdown 編寫內容，PR 提交等），Jekyll 以及 Github Pages 服務來提供一個高質量的文檔。Github Pages 提供給咱們文檔團隊的好處一樣對每個運行 Github Pages 的站點都是可用的。

隨着咱們將文檔遷移到 Pages，咱們不再用重建任何新的組件了。咱們花費了更少的時間創建一些東西而且更多的時間去討論咱們的團隊和公司應該有什麼樣的工做流程。經過使用和 Github 用戶同樣的託管系統，咱們可以提供更好更快的文檔系統。咱們內部的工做流程是的咱們變得更有成效，而且是的咱們從未如此方便的提供版本特徵，例如版本化內容。

若是你對 Github 文檔流程的簡歷有任何的疑問，不管什麼時候，Github 都很是樂於幫助你們！