提供书写良好的文档，可以帮助人们理解并很好地使用你的项目，而且人们还能够很容易地参与你的项目并作出贡献，但这仍不够。基于文档服务的底层系统能够使任何人——包括你或你的团队写文档更轻松。
对于文档的编写，最大的难点不是如何配置工具，或者要弄清楚怎么部署更新，而在于如何斟词酌句。GitHub文档制作团队的成员有着丰富的工作背景，包括使用原生的基于XML的写作工具，以及复杂的CMS系统。但我们并不想使用那些工具，因此我们花费了大量时间和精力来配置我们自己的文档制作流程和工作计划。
以前我们也谈论过怎么使用GitHub构建GitHub；如下就是我们怎样使用 GitHub Pages 每月向数百万读者提供 我们的GitHub帮助文档。 我们以前的流程几个月前，我们把帮助系统的站点从自建的Rails程序迁移到了 Github Pages 上的Jekyll。之前我们的帮助系统需要两个相互独立的项目仓库：
我们的 Rails 应用程序托管在一个第三方平台上。随着代码的不断更新升级，我们将它部署在了 Hubotand Chatops ，这些都是我们在维护 Github 主站的闲暇之余完成的。
下面是一个简单的示例，@neveretand@bernars给我们展示了一下我们正常的工作流程：
使用pull requests进行工作很有意思，因为它正好和我们团队使用的 Github工作流程是一致的。并且Markdown 的语法能让我们快速高效地表达出新特性的独到之处，所以我们写文档时，对它情有独钟。 然而，我们的 Rails 程序维护起来相当麻烦：
我们意识到，其实我们可以做得更好。 我们的新流程当 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 )特异性进行分组；其对应的值为下面的Markdown源码( "In the upper-right corner...”)。使用使用合适的语法，我们只需要简单一步就能在不同页面引用创建一个新的仓库。
随着Github的界面变化，我们也许需要修改图片或者重新定义方向的指向。这样我们只需要借助内容参考，仅仅在改变一个地方而不是很多地方。 |
1 2 3 4 5 | {% if site.audience != '11.10.340' %}This new feature...{% endif %} |
以上的实现仅仅利用了Jekyll的核心功能，我们并不需要为此创建或者维护任何其他的东西。
