Foreword
最近在《GitHub + Markdown 的新轻型技术写作模式速览》中带大家快速了解了一下 GitHub + Markdown 这种比较新的技术写作模式。不出所料，确实有些小伙伴在读了上一篇分享后存在诸多疑惑与顾虑。
如果你已经从事技术写作多年，已经用惯了某个典型的传统工具，也没必要对 GitHub + Markdown 这种低成本极敏捷的模式嗤之以鼻。它是一种被越来越多的技术型创新企业采用的文档解决方案。
很多全球知名产品或项目的文档方案都是使用的 GitHub + Markdown，例如 Docker，Kubernetes 等，如果你没听说过，可以去官网看看它们的文档。此外，2017 年 10 月份在 Stuttgart 举行的 tcworld conference 2017 上，也有与会嘉宾分享了 Markdown 与 GitHub 结合的文档模式，讲的都是一些特别基础的东西。
附上嘉宾的 PPT 链接，语言为德语（可使用 Google Translate 辅助理解），感兴趣的小伙伴可以去看一下：http://conferences.tekom.de/fileadmin/tx_doccon/slides/1792_Dr_Jekyll_und_Mr_Markdown_Dokumentieren_auf_GitHub.pdf
本文主要内容结构：
- 解答读者提出的 GitHub + Markdown 模式相关的几个问题
- 采用 GitHub + Markdown 模式的文档呈现效果如何
- GitHub + Markdown 的个人使用体验
GitHub + Markdown 模式的相关问题解答
问题 1：这种模式是只适合创业型的企业吧？如果公司已经有了 long established 的文档样式要求的话，这种写作模式就不太适合了吧？
GitHub + Markdown 这种模式比较适用于创业公司，尤其是技术型的创业公司。但我认为，也不能绝对地说它只适用于创业公司，而应该以一种发展的眼光来看问题。绝大多数公司都是从创业阶段走过来的，数年之后或者十几年之后，GitHub + Markdown 这种模式在技术写作领域所占的比重很可能会越来越大。
跟大家分享这种技术写作模式呢，并不是说让大家都转换到这种写作模式上来。对于那些长久以来已经有固定模式要求的公司来说，确实不适合，这也不是某一个 Technical Writer 可以想改就改的。另外，不同的公司对文档交付物的展现形式有不同的要求，这也会影响写作工具的选择。
我更想传达的意思是这样的：作为一个希望成长的 Technical Writer，应该始终保持一种好奇心，了解技术传播、技术写作领域的发展动态，一些新模式的行业实践，以及可提高自己工作效率的新工具等，扩展自己的视野。
而不是工作年限在增长，却只局限在自己工作所用的那一种工具上，对行业的发展全然不知。这样很容易被不断发展的世界和行业所淘汰哦~
问题 2：长文档是否适用？对于多图片和表格的支持如何？
- GitHub + Markdown 这种模式可以很好地支持长文档，对单个文档的长度没有限制。
这里有个问题，多长的文档算长呢？如果跟用 XML 编辑器写的 DITA 类型的一个 topic 相比的话，那一篇 Markdown 文档可以长出好多。当然啦，文档可长可短，全由 Writer 来决定，就好比给你提供了一张可满足你基本需求的白纸，任凭你自由发挥。 - GitHub + Markdown 模式可以较好地支持基本的图片与表格需求。
如果你对图片与表格有一些额外的复杂需求，可以请前端工程师配合实现。下文会给大家看几个图片与表格的实例~
问题 3：支持的文档输出格式包括哪些呢？输出 PDF 是否要借助其他工具？
在 Markdown 编辑中写完的单篇文档可以直接导出为 HTML 和 PDF，例如 MacDown 编辑器。不过，个人在实际工作中，目前暂时没有将单篇 Markdown 文件导出为其它格式的需求，因为大多数情况下，是将写好或修改好的 Markdown 文件直接提交到 GitHub 上。
如果需要将一个产品的全部文档导出为一个 PDF，可以找前端工程师配合支持。
问题 4：有没有特别具体的 GitHub + Markdown 的使用流程？
在上一篇里，给大家简单列了下基本的流程，没有详细展开。不同的产品对于创建和修改文档的步骤也会有一些差异。想实际操练的小伙伴，可以先自行在网上搜索一下相关流程，相信你一定可以找到。
采用 GitHub + Markdown 的文档呈现效果如何？
采用 GitHub + Markdown 的文档实践很多，这里以 Docker、Kubernetes 和 TiDB 的用户文档为例，带大家了解一下采用这种模式的文档长什么样子，图片和表格的呈现如何，以及这种模式特有的一些文档辅助功能。
- Docker Documentation: https://docs.docker.com/
- Kubernetes Documentation: https://kubernetes.io/docs/
- TiDB Documentation: https://www.pingcap.com/docs/
1. 文档主页的呈现
即便都采用 GitHub + Markdown，不同的产品文档呈现效果也不同，这要看对文档呈现的需求和设计了。采用这种模式，通常会需要前端工程师的支持，以实现一些较为高级的呈现效果。
一种典型的文档页面展现布局是：分为左中右三栏，左侧为文档导航目录，中间为文档正文，右侧为当前页面的导航。
▲ Docker 文档主页
▲ Kubernetes 文档主页
▲ TiDB 文档主页
2. 表格和图片的呈现
在上文的问题解答中，已经讲述了 GitHub + Markdown 对表格的支持。下面给大家看下呈现效果~
- 表格
▲ TiDB 文档表格 - 官网呈现效果
▲ TiDB 文档表格 - GitHub 呈现效果
大多数情况下，GitHub 上的内容与文档官网上的内容呈现是一致的，但有时为了在官网上实现特定的呈现效果，需要牺牲一下 GitHub 上内容的可读性。例如：
▲ Docker 文档表格 - 官网呈现效果
▲ Docker 文档表格 - GitHub 呈现效果
- 图片
▲ Docker 文档图片 - 官网呈现效果
一般来讲，图片的呈现在官网和 GitHub 上是一致的，但也有少数情况不一致。例如，如果需要在图片下方加个居中的图片标题，官网的显示是正常的，GitHub 上会显示在左侧，未完全解析。
3. 文档更新动态的呈现
采用 GitHub + Markdown 这种模式，可以将一篇文档的更新动态呈现在官网的文档页面，即该篇文档最近一次更新是什么时间。这个功能可以让用户知晓某个产品的文档维护动态，有利于增加对产品的信心。文档不断在更新，不断在改进，说明产品也在不断改进。
▲ Kubernetes 文档更新动态
▲ TiDB 文档更新动态
4. 用户参与和反馈的入口
采用 GitHub + Markdown 这种模式，可以与用户便捷地互动，及时获取用户的反馈意见，让用户参与到文档的改进中来。许多产品的官方文档页面都添加了收集用户反馈或者让用户直接参与文档修改的入口，示例如下：
- 收集用户反馈：GitHub Issues
▲ Docker 文档用户反馈官网入口
▲ Docker 文档用户反馈 GitHub 页面
▲ Kubernetes 文档用户反馈官网入口
▲ Kubernetes 文档用户反馈 GitHub 页面
- 让用户参与文档修改：GitHub Pull Requests
▲ Docker 文档用户参与修改的官网入口
▲ Docker 文档用户参与修改的 GitHub 页面
▲ Kubernetes 文档用户参与文档修改的官网入口-1
▲ Kubernetes 文档用户参与文档修改的官网入口-2
▲ Kubernetes 文档用户参与文档修改的 GitHub 页面
GitHub + Markdown 的个人使用体验
至今，我已使用 GitHub + Markdown 一年多。个人体验中最明显的一点是：提交或修改文档尤为简单敏捷。
不过，若要将产品的全部用户文档导出为 PDF，实现起来并不简单，很可能不是一般的 Technical Writer 可以解决的。这时，就只能提需求然后寻求技术小伙伴的支持了。
所以，这种模式并不一定适合所有的产品。它是一种新的轻型敏捷的技术文档写作模式，但到底要不要选择这种模式，需要综合考虑实际的文档需求、成本和时间等再做决定。
Afterword
无论从事什么工作，都应该时刻保持好奇心，及时了解行业发展动态，以一种开放的心态去对待新事物。要不断学习与个人发展相关的新技能，因为不进则退哦。
附本文示例链接
表格呈现示例链接：
- https://docs.docker.com/ee/supported-platforms/#on-premises
- https://github.com/docker/docker.github.io/blob/master/ee/supported-platforms.md#on-premises
- https://www.pingcap.com/docs/op-guide/recommendation/
- https://github.com/pingcap/docs/blob/master/op-guide/recommendation.md
图片呈现示例链接：https://docs.docker.com/ee/#orchestration-platform-features
文档更新动态示例链接：
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/
- https://www.pingcap.com/docs/op-guide/ansible-deployment/
用户参与和反馈示例链接：
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/
- https://github.com/kubernetes/website/edit/master/content/en/docs/concepts/storage/persistent-volumes.md
- https://docs.docker.com/ee/supported-platforms/
- https://github.com/docker/docker.github.io/edit/master/ee/supported-platforms.md
你可能想读：
技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
Technical Writer 日常工作中好用的小工具
如何使用颜色来提高技术文档的可读性？
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
英语技术文档的标题到底该大写还是小写？
如何使用正则表达式批量添加和删除字符？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记
-END-
网友评论