技术文档方案 | GitHub + Markdown 的深度实践

2018-08-22 本文已影响70人 Lilian_Lee

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 上。