Github 是如何用 Github 撰写 Github 文档的

原文:https://github.com/blog/1939-...
译者:@公子html


一份好的文档可以帮助人们理解,使用以及贡献代码到你的项目中,但这只是一个生成文档的方程式的一半。生成文档的底层系统使得人们,不管是你仍是一块和你工做的团队,撰写文档变得更加容易。前端

撰写文档最难的一部分既不是编写配置工具,也不是说明项目应该如何搭建和升级,而应该是文档的遣词造句。Github 文档团队的成员大多都是有使用XML文档生成工具和复杂的CMS系统背景的。正由于他们饱受了这些工具的折磨,因此为了避免再使用这些工具咱们花费了大量的时间去思考咱们本身的文档生成流程和设置。git

咱们以前已经讨论过咱们如何使用 Github 创建 Github 了。在这里咱们将着重讨论一下咱们如何使用 Github Page 服务运行 Github 帮助文档 (目前每个月有上百万的访问量)的。github

咱们之前的流程

几个月前,咱们把帮助文档的地层从 Rails 程序迁移到 Jekyll 托管在了 Github Pages 上。以前咱们的帮助文档须要两个相互独立的项目仓库:web

  • 用于托管维护网站、管理网站所用资源和文档搜索加强的 Rails 应用程序
  • 用户托管由一大堆 Markdown 文件组成的网站具体内容

咱们的 Rails 应用程序托管在一个第三方平台上。随着对代码的日益升级,咱们将它部署在了 Hubot ,这些都是咱们在维护 Github 主站的闲暇之余完成的。(译者注:Hubot 是 Github 开源的一款自动化智能化执行命令的机器人项目,具体刻参考 Hubot 的主页。)数据库

咱们正常的撰写流程多是这个样子的:缓存

  1. 当有新特征开发出来的时候文档团队首先编写好文档内容
  2. 建立一个新的 issue 去追踪这个特征
  3. 当文档更新完毕一切就绪以后,咱们会发起一个 pull request 去迭代更新文档内容。
  4. PR 发起成功后,咱们会使用 @ 方式提醒团队(好比 @github/docs )并会让队友们审查一下咱们的内容。
  5. 当这个特征开发完毕已经上线的时候,咱们会合并以前建立的 PR。 使用 webhook 可以帮助咱们在 内容仓库 快速激活咱们部署的 Rails 应用程序。webhook 承担了负责更新数据库的任务。

下面是一个简单的示例给咱们展现了一下咱们正常的工做流程:sass

e65dc512-94eb-11e4-8fff-8e02f9bed3d4.png

使用 PR 进行工做是很是神奇的,由于它正好和咱们在团队中使用的 Github 工做流程是一致的。而且咱们喜欢用 Markdown 语言书写,更由于 Markdown 的语法能让咱们不用花费多少时间就有效的描述新特征的全部内容。安全

然而,咱们的 Rails 加强程序安装设置起来却很是的麻烦:ruby

  • 因为咱们依赖外部主机,因此咱们须要专门的员工在咱们的工程,运维和安全团队中监控站点和他们发起的响应事件。
  • 咱们的文档团队并不能方便的在本地观察内容的变化。虽然咱们使用的是 Markdown 编写的内容,能够实时预览,可是咱们能忍须要配置一个本地的 Rails 应用服务去运行脚本将内容导入到数据库中而后观察其在网站上的最终效果。
  • 虽然咱们不断的调整 Rails 的服务器,可是咱们注意到用户的请求依旧使得网站访问变得很是缓慢。因为 HTML 页面是动态生成的,这就须要对数据库进行请求,这就耗费了不少时间。为了加快访问速度,咱们还须要找寻更强大的缓存策略。

咱们知道咱们是时候作出改变作的更好了。

咱们的新流程

Jekyll 2.0 发布的时候,咱们看到了曙光,是时候该把咱们这套该死的流程换成纯静态站了!特别是新增长的 Collections 文档类型能让你定义你须要的文件结构。另外,Jekyll 2.0 还增长了 SassCoffeeScript 的支持,这将使得编写前端代码变的更为简单便捷。

开源的好处在于它是开放的。咱们迁移到 Jekyll 后,咱们也向 Jekyll 发起了不少 PR 使得它能更好的服务 Github Pages 的用户。

使用了 Jekyll 以后,咱们的工做流程发生了小小的变化。咱们仍然使用 Markdown 而且咱们仍然须要将内容 PR 到仓库以便其它人审查。可是当咱们发起的 PR 被合并以后,Github Pages 网站将会在几秒内自动快速建立并部署。

下面是咱们就如何使用 Jekyll 的核心功能以及咱们使用的一些强化 Github 帮助文档站点的插件列了一个简单的纲要。

咱们使用的 Gems

咱们尽量的依赖 Jekyll 代码自己的功能去尽量减少咱们依赖本身维护的自定义插件,这样能够减小咱们的额外压力。

Jekyll 2.0 内自带的新的插件 Converter 使得用户能够将任何 标记语言书写的文件转换成 HTML。这样用户能够随便创做它的内容,Jekyll 只负责运行最后生成的 HTML文件就行了。举个例子,只要你会,你甚至可使用 AsciiDoc 语法书写你的内容。

最后,咱们开发了 jekyll-html-pipeline 插件,是咱们以前开源的 html-pipeline 在 Jekyll 上的加强版。这个确保了咱们的帮助站点的内容在 Github 上的任何地方看起来都是同样的。咱们同时也开发了咱们本身的 Markdown filter 插件去提供一些语法扩展使得咱们编写文档更方便。

搜索

老流程的 Rails 网站中,咱们使用了 ElasticSearch 对咱们的数据库进行索引并加强了 Github 帮助文档的搜索系统。

如今,咱们使用 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**.
           ![New repository menu](/assets/images/help/repository/repo-create.png)

此时咱们的键为 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 UI 的变化,咱们也许须要修改图片或者从新定义某些地方的指向。这个时候,咱们仅仅只须要修改一个地方就能完成咱们的变化,比起之前须要修改全部的地方简直不知道方便了多少倍。

版本化显示文档

另外一个随着这次变化带来的好处就是咱们如今可以显示多版本的帮助文档。随着 Github 企业版 2.0.0 的发布,咱们对以前的 11.10.3 版本如今的 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 在他们的测试中模拟网站的交互。在咱们的静态站点实现一个相似的工具这个主意看起来很疯狂?并不! Github 的 bkeepers 4年前的一篇文章 已经谈论过这个问题了。当时,咱们建立了更强大的测试工具,它涵盖了咱们的内容测试和网站行为测试。举个例子来讲,咱们经过检查 YAML 文件中的键是否存在来确认某个内容引用是否有效,又或者说咱们会测试咱们的 JavaScript 代码是否运行良好。

咱们的帮助文档在 CI(译者注:持续集成系统)上运行,这样确保了用户不会拿到损坏的内容。

7adf83be-84a3-11e4-8c41-1b3448a2f7df.png

速度

正如咱们以前提到的,新的流程使得咱们的 Pages 服务比以前使用 Rails 系统的时候有了标志性的加快。这其中一部分缘由固然是由于新站点是一堆静态的 HTML 文件的集成——咱们不须要向数据库获取任何内容。更值得注意的是,咱们花费了大量的时间配置咱们的 Pages 服务使得任何人运行它都是同样的快速。咱们有的好处,好比使用 CDN 分布式部署站点资源等,这些对每个 Github 用户来讲也一样是可用的。

576d7e46-849d-11e4-8986-0bb86c2a58d5.png

让 Github Pages 为你工做

文档团队经过 Github 利用 Github 的工做流程(译者注:即前文提到的 Markdown 编写内容,PR 提交等),Jekyll 以及 Github Pages 服务来提供一个高质量的文档。Github Pages 提供给咱们文档团队的好处一样对每个运行 Github Pages 的站点都是可用的。

随着咱们将文档迁移到 Pages,咱们不再用重建任何新的组件了。咱们花费了更少的时间创建一些东西而且更多的时间去讨论咱们的团队和公司应该有什么样的工做流程。经过使用和 Github 用户同样的托管系统,咱们可以提供更好更快的文档系统。咱们内部的工做流程是的咱们变得更有成效,而且是的咱们从未如此方便的提供版本特征,例如版本化内容。

若是你对 Github 文档流程的简历有任何的疑问,不管什么时候,Github 都很是乐于帮助你们

相关文章
相关标签/搜索