技术写作工具 | GitHub + Markdown 的新轻型技术写作模式速览

Foreword

2018 年 6 月初，有位读者在后台留言向我咨询了一个关于技术写作工具的问题。那位读者从事技术写作近两年，在新入职一家公司后，一切从零开始，包括工具的调研和选用。

最后 TA 选定的是 Adobe FrameMaker，进行 DITA 结构化写作，但是在发布为 PDF 时一直有些序号等问题不知道如何解决。由于客服解决问题的效率比较低，难以得到帮助。

于是，便向我咨询是否认识对这个软件比较熟知的人，以帮助其解决问题。

说到 Adobe FrameMaker，凡是对技术写作稍有了解的人，大概都知道这个工具。我在北大读研期间，有门课程叫“英语技术文档写作”，记得当时做作业用的是 Oxygen，后来的技术写作大赛上用的就是 FrameMaker。

FrameMaker 给我的感觉是太重了，个人不大喜欢，近两年也没有再用过。

后来实习用的是 Arbortext，这个工具就轻很多，上手也快，轻松地自学两天就可以开始用它来写文档、在正式工作中交付文档了。这里我说的“两天”不是虚数，是真的两天~

说回那个读者的问题，后来我跟 TA 简单聊了下 FrameMaker，然后把一个 FrameMaker 技术交流群的二维码发给了 TA。

那么，我现在用的工具是什么呢？老读者应该已经知道了，就是接下来要聊的 GitHub + Markdown，一种轻型技术写作模式，尤其适用于创业公司。

这种模式走的是极简主义的风格，特别轻；说它新，是因为很多从事技术写作的小伙伴还不知道有这种模式。没关系，你马上就知道啦！

1. GitHub

GitHub 是一个基于 web 的提供版本控制和托管服务的平台。大多数程序员都比较熟悉，上面有很多开源项目，可以参与进去，也可以自己创建或维护一个项目。

GitHub: https://github.com/

我的 GitHub 个人主页是：https://github.com/lilin90

我的 GitHub 个人主页

我日常工作中创建的文档或对文档的修改都会记录在 GitHub 上，一目了然，也非常方便之后查阅。如下图所示：

GitHub 个人主页动态记录

个人的 Pull Requests 记录

2. Markdown

Markdown 是一种轻量级标记语言，这个语言的目的是希望大家使用“易于阅读、易于撰写的纯文字格式，并选择性的转换成有效的 XHTML（或是 HTML）”。

关于 Markdown，我已经在之前的文章中详细地介绍过，小伙伴们可以戳下面的链接去查看。

已分享的内容包括：Markdown 简介、基本语法、常见的编辑器（含 macOS、Windows 和在线编辑器），如何为 Markdown 文件自动生成目录，以及我平时使用最多的 Visual Studio Code。

• Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
  • 简介、语法、编辑器
• 实用帖 | 如何为 Markdown 文件自动生成目录？
  • 自动生成目录 + Visual Studio Code
• Technical Writer 日常工作中好用的小工具
  • Visual Studio Code 与 MacDown

3. GitHub + Markdown

现在你已经对 GitHub 和 Markdown 有了一个基本的了解，那么，Technical Writer 在工作中使用它们的基本流程是怎样的呢？

以创建一个新的文档为例，大致的流程如下：

1. 新建一个 branch；
2. 在新建的 branch 上创建新的 Markdown (.md) 文件；
3. 撰写文档并完成；
4. 提交新文档，提一个 Pull Request；
5. Reviewer 进行 review 并通过；
6. 将新文档 merge 到 master branch。

然后，你所创建的新文档就可以在 GitHub 和公司官网的文档菜单下正常显示啦！

当然，上面的流程里我省略了一些细节步骤，熟悉了之后，操作起来很简单很迅速。简言之，就是用 Markdown 编辑器来写文档，然后提交到 GitHub 上。

如果你对此比较感兴趣，可以自己去搜索尝试一下，网络上有很多资源可供参考，别忘了 GitHub 的官方帮助文档哟~

Afterword

这一篇呢，主要是带大家快速了解一下 GitHub + Markdown 的技术写作模式。因为这种模式使用的是开源产品，所以会极大地节约文档成本；从文档需求到文档交付的周期也可以特别短，尤为敏捷。

或许有些小伙伴对 GitHub + Markdown 依然还有很多疑惑，下一篇中我会跟大家分享一下 GitHub + Markdown 的深度实践，看看那些用这种模式的产品文档都是什么样子的，让大家有个更直观的感受。

如果你有什么问题，欢迎留言交流哦~

附上开头提到的 FrameMaker 技术交流群的二维码，扫需：

你可能想读：

技术文档诞生记 | 完整的技术写作流程是怎样的？
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-