提供書寫良好的文檔，可以幫助人們理解並很好地使用你的項目，而且人們還能夠很容易地參與你的項目並作出貢獻，但這仍不夠。基於文檔服務的底層系統能夠使任何人——包括你或你的團隊寫文檔更輕松。
對於文檔的編寫，最大的難點不是如何配置工具，或者要弄清楚怎麼部署更新，而在於如何斟詞酌句。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 使用教程圖文詳解 http://www.linuxidc.com/Linux/2014-09/106230.htm
Git 標簽管理詳解 http://www.linuxidc.com/Linux/2014-09/106231.htm
Git 分支管理詳解 http://www.linuxidc.com/Linux/2014-09/106232.htm
Git 遠程倉庫詳解 http://www.linuxidc.com/Linux/2014-09/106233.htm
Git 本地倉庫（Repository）詳解 http://www.linuxidc.com/Linux/2014-09/106234.htm
Git 服務器搭建與客戶端安裝 http://www.linuxidc.com/Linux/2014-05/101830.htm
Git 概述 http://www.linuxidc.com/Linux/2014-05/101829.htm
分享實用的GitHub 使用教程 http://www.linuxidc.com/Linux/2014-04/100556.htm
GitHub 的詳細介紹：請點這裡
GitHub 的下載地址：請點這裡
英文原文：How GitHub uses GitHub to document GitHub
