# 書寫文檔 一個程序員，最基本的是需要寫代碼，代碼之中其實就包含了注釋。如果是一個系統或者庫文件，其實還需要書寫文檔以配合。本文就交大家如何書寫文檔。 ### github如何管理文檔 討論一下我們如何使用 [Github Page](https://pages.github.com/) 服務運行 [Github 幫助文檔](https://help.github.com/) （目前每月有上百萬的訪問量）的。 ### 以前的流程 - 用于托管維護網站、管理網站所用資源和文檔搜索增強的 Rails 應用程序 - 用戶托管由一大堆 Markdown 文件組成的網站具體內容 我們正常的撰寫流程可能是這個樣子的: - 當有新特征開發出來的時候文檔團隊首先編寫好文檔內容 - 創建一個新的 issue 去追蹤這個特征 - 當文檔更新完畢一切就緒之后，我們會發起一個 pull request 去迭代更新文檔內容。 - PR 發起成功后，我們會使用 @ 方式提醒團隊（比如 @github/docs ）并會讓隊友們審查一下我們的內容。 - 當這個特征開發完畢已經上線的時候，我們會合并之前創建的 PR。 使用 webhook 能夠幫助我們在 內容倉庫 快速激活我們部署的 Rails應用程序。webhook 承擔了負責更新數據庫的任務。 ### 新的流程 當 Jekyll 2.0 發布的時候，我們看到了曙光，是時候該把我們這套該死的流程換成純靜態站了！特別是新增加的 Collections 文檔類型能讓你定義你需要的文件結構。另外，Jekyll 2.0 還增加了 Sass 和 CoffeeScript 的支持，這將使得編寫前端代碼變的更為簡單便捷。 ### 參考資料 - [Github 是如何用 Github 撰寫 Github 文檔的](http://segmentfault.com/blog/openwrt/1190000002473246) - [markdown + git 最適合程序員的wiki系統](http://examplecode.github.io/tools/2014/09/26/install-gollum-in-mac-109/) - [gollum](https://github.com/gollum/gollum): github的文檔系統。