Github 是如何使用 Github 來處理 Github 文檔的

Github 是如何使用 Github 來處理 Github 文檔的

提供書寫良好的文檔，可以協助人們理解並很好地使用你的項目，而且人們還能夠很容易地參與你的項目並作出貢獻，但這仍不夠。基於文檔服務的底層系統能夠使任何人——包括你或你的團隊寫文檔更輕鬆。

對於文檔的編寫，最大的痛點不是如何組態工具，或者要弄清楚怎麼部署更新，而在於如何斟詞酌句。GitHub文檔製作團隊的成員有著豐富的工作背景，包括使用原生的基於XML的寫作工具，以及複雜的CMS系統。但我們並不想使用那些工具，因此我們花費了大量時間和精力來配置我們自己的文檔製作流程和工作計劃。

以前我們也談論過怎麼使用GitHub構建GitHub；如下就是我們怎樣使用 GitHub Pages 每月向數百萬讀者提供 我們的GitHub協助文檔。

我們以前的流程

幾個月前，我們把協助系統的網站從自建的Rails程式遷移到了 Github Pages 上的Jekyll。之前我們的協助系統需要兩個相互獨立的項目倉庫：

 

• 負責營運網站、管理網站資源，以及實現文檔搜尋的 Rails 應用程式

• 由一大堆 Markdown 檔案組成的網站具體內容

我們的 Rails 應用程式託管在一個第三方平台上。隨著代碼的不斷更新升級，我們將它部署在了 Hubotand Chatops ，這些都是我們在維護 Github 主站的閑暇之餘完成的。
 我們正常的撰寫流程可能是這個樣子的：

 

• 當有新特徵開發出來的時候文檔團隊首先編寫好文檔內容

• 建立一個新的 issue 去追蹤這個特徵

• 當文檔更新完畢一切就緒之後，我們會發起一個 pull request 去迭代更新文檔內容。

• PR 發起成功後，我們會使用 @ 方式提醒團隊（比如 @github/docs ）並會讓隊友們審查一下我們的內容。

• 當這個特徵開發完畢已經上線的時候，我們會合并之前建立的 PR。 使用webhook能夠協助我們在內容倉庫快速啟用我們部署的 Rails 應用程式。webhook 承擔了負責更新資料庫的任務。

下面是一個簡單的樣本，@neveretand@bernars給我們展示了一下我們正常的工作流程：

 

使用pull requests進行工作很有意思，因為它正好和我們團隊使用的 Github工作流程是一致的。並且Markdown 的文法能讓我們快速高效地表達出新特性的獨到之處，所以我們寫文檔時，對它情有獨鐘。

然而，我們的 Rails 程式維護起來相當麻煩：

• 由於我們的主機是外部託管，所以我們需要工程，營運和安全團隊的專業人員即時監控網站健全狀態，並能及時處理突發事件。

• 我們的文檔團隊並不能方便的預覽內容的變化。雖然我們使用 Markdown 編寫內容，可以即時預覽，但是我們仍然需要配置一個本地的 Rails 應用服務去運行指令碼將內容匯入到資料庫中然後觀察其在網站上的最終效果。

• 雖然我們不斷的調整 Rails 伺服器設定，而使用者發起請求後響應速度依然緩慢。這是因為 HTML 頁面是動態產生的，需要對資料庫進行頻繁訪問，即便運用更為強大的緩衝策略，依然收效甚微。

我們意識到，其實我們可以做得更好。

我們的新流程

當 Jekyll 2.0 發布的時候，我們意識到是時候使用靜態網站了！特別是 Collections文件類型這個新特性使得定義自己的檔案結構成為可能。不僅如此，Jekyll 2.0 還增加了 Sass 和 CoffeeScript 的支援，讓前端代碼的編寫更簡單。

開源的好處在於它是開放的。我們遷移到 Jekyll 後，我們也向 Jekyll項目發起了很多pull requests，貢獻代碼，使得它能更好的服務 Github Pages 的廣大使用者。

這時，我們的工作流程發生了小小的變化。但我們仍然使用 Markdown ，將寫好的內容提交到倉庫供他人審校。當我們的提交被合并之後，Github Pages 網站將會在幾秒內自動快速建立並部署。

下面是我們就如何使用 Jekyll 的核心功能以及對 Github 協助系統起增強效果的外掛程式列了一個簡單的綱要。

我們的法寶

我們主要依靠 Jekyll 核心代碼的功能來完成任務，這樣更省心省力，而不是將大量精力用於維護自訂外掛程式。

Jekyll 2.0 提供的全新外掛程式 Converter 可以將任何標記自動轉換成 HTML。這樣使用者寫文章就可以無拘無束，Jekyll 只負責運行最後產生的 HTML檔案就好了。比如，你可以使用 AsciiDoc 文法發貼子。

最後，我們開發了 jekyll-html-pipeline 外掛程式，是我們之前開源的 html-pipeline 在 Jekyll 上的增強版。這個確保了我們的協助網站的內容在整個Github 上沒有任何差異。同時我們也用自己開發的 Markdown filter 外掛程式提供一些文法擴充，進一步降低了文檔編寫的難度。

搜尋

在之前的Rails網站上，我們使用了Elasticsearch 供應商索引我們的資料庫並為我們的協助網站實現了搜尋系統。

現在，我們使用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**.
      

我們的鍵根據 (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的介面變化，我們也許需要修改圖片或者重新定義方向的指向。這樣我們只需要藉助內容參考，僅僅在改變一個地方而不是很多地方。

版本化的文檔

另一個改變帶來的好處是能夠提供版本化的協助文檔。隨著Github企業版2.0的發布，我們開始提供之前的11.10.340版本和現在的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在他們的測試中類比網站互動。在我們的靜態網站中實現一個類似的工具，這個想法瘋狂嗎？不！我們的工程師@bkeepers 四年前寫了一篇部落格討論了這個問題。這樣，我們有能力進行一次更強有力的測試，這測試涵蓋我們的內容已和網站行為。比如，我們通過檢查YAML檔案中的鍵是否存在確認某個內容是否有效，或者我們會檢測javascript代碼是否運行良好。

我們的協助文檔運行在CI上以確保使用者不會拿到損壞的內容：

速度快

如上所述，比起原來的Rails應用，我們的新Pages實現在速度上有極大的提升。部分原因在於，網站內容主要是大量的靜態HTML檔案——無需訪問資料庫。但最重要的是, 我們花費了大量時間來最佳化Pages伺服器使得訪問速度狂飆 。另外，包括提供CDN這樣的服務條件，我們也能一一滿足。

讓Github Pages為你工作

Github上的文檔團隊可以利用Github工作流程，Jekyll 2.0和Github Pages來建立高品質的文檔。Github Pages 提供給我們的文檔團隊的好處同樣適用於任何使用Github Pages的使用者。

隨著我們將文檔遷移到Pages，我們再也不需要重建任何新的組件。我們花了很少時間建立一些東西並花了很多時間討論怎樣的工作流程對我們團隊和公司才有意義。通過使用和廣大Github使用者一樣託管系統，我們能提供更好更快的文檔系統。我們內部的工作流程使我們的工作效率顯著提高，並且提供一些我們以前從未提供過的功能比如說版本化的文檔。

如果你對我們的流程有任何疑問，無論何時，我們都很樂意協助大家。

GitHub 教程系列文章： 

GitHub 使用教程圖文詳解   

Git 標籤管理詳解  

Git 分支管理詳解  

Git 遠程倉庫詳解  

Git 本地倉庫（Repository）詳解  

Git 伺服器搭建與用戶端安裝   

Git 概述  

分享實用的GitHub 使用教程  

GitHub 的詳細介紹：請點這裡
GitHub 的：請點這裡

英文原文：How GitHub uses GitHub to document GitHub

本文永久更新連結地址：