提供书写良好的文档可以帮助人们理解并很好地使用你的项目，而且人们还能够很容易地参与你的项目并作出贡献，但这仍不够。基于文档服务的底层系统能够使任何人(包括你或你的团队)写文档更轻松。

对于文档的编写，最大的难点不是如何配置工具，或者要弄清楚怎么部署更新，而在于如何字斟句酌。GitHub文档制作团队的成员有着丰富的工作背景，包括使用原生的基于XML的写作工具，以及复杂的CMS系统。但我们并不想使用那些工具，因此我们花费了大量时间和精力来配置我们自己的文档制作流程和工作计划。

下面我们介绍怎样使用 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 页面是动态生成的，需要对数据库进行频繁访问，即便运用更为强大的缓存策略，依然收效甚微。

我们意识到，其实我们可以做得更好。

123下一页阅读全文

分页导航

1.以前的流程2.新流程3.让Github Pages为你工作