7.9 KiB
像代码开发一样撰写文档
不想让书写滞后于你的思考？或许你该尝试一下全新的写作方式。
很多工程师与手工艺者都对他们使用的工具有特别的要求。为了顺利的完成工作，你需要最好的工具和使用它们的技巧。软件开发中最好的工具在应用到其他的数字创作领域中也可以是很强大的。Docs as Code (译注：代码化文档)的方式就是很好的例子。Doc as Code 意味者使用与代码开发相同的工具与工作流来撰写文档。Doc as Code 的支持者认为这样的方式可以在降低作者的工作符负荷的同时保证更好的文档结构。
文本格式与源文件控制
从传统的写作平台切换到 Docs as Code 方式时，最主要的调整是写作内容保存在基于文本的标记格式中。这一转变使得基于纯文本材料的工具都适用于文档写作。当你选择 DocBook， Markdown 或者其他的标记语言时，从只使用一种工具到使用一种标准格式配合多种工具是一种巨大的转变。
找到支持你的工作流程的工具是非常重要的。在 Docs as Code 项目中，很多开发者使用他们的 代码编辑器。考虑到他们已经是这些工具的高阶用户，一切都很顺利。而找到适合团队里适合其他专业从业者，比如技术撰稿、编辑、信息架构师和文档产品责任人，的工具可能需要一番努力。这里有一些选项可兹参考：
- 各种优秀的 Markdown 编辑器之一是可行的
- 附带良好的预览工具的代码编辑器可能更适合非程序员
- 流行的 Git 托管服务的网页界面尤其适用于偶尔有需要的贡献者
一旦内容以标记语言的格式安全保存就可以使用版本控制进行管理，比如 Git。Git 相比大多数文档平台具有更多的功能：
- 清晰详细的文档版本历史：谁在什么时候改变了什么。
- 简明的并行修改过程支持。在 Git 中使用分支工作意味着任何人可以做出他们想要的任何改变并在最后合并所做的更改。
- 高级的协作与审查工具。所有的源代码管理平台都设计支持评审每一条细节变更并在足够的讨论后使每个人都确信改变可以继续的流程。
- 自动质量检查，比如拼写检查和链接检查。这不仅节省了时间，而且可以发现以前无法发现的错误。
源代码管理有很多优点。但要记住，如果你准备入门源代码管理，它有一定的学习曲线。这是一些有助于入门的优秀的学习资源和作者文章。你也可以让具有好奇心的文档作者自行寻找对他们有用的学习材料，而不是请你的工程师来培训他们。(探寻他人的学习历程是最困难的学习方式)
拉取请求和评审循环
所有的源代码管理平台都围绕拉取请求这一概念设计，这有时也称为合并请求。有时候，某些团队先将一系列改变整合到一起然后向主项目发起要求修改被拉取的请求。不过从许多方面来说，在文档中一次处理多个变更比在代码中更容易。改变文档中某处的一篇文章比之更改代码并找出有哪些地方依赖它具有更小的副作用。
最强大的协作工具是 diff，它可以通过一个易于察觉的方式展示旧版本与新版本之间的差异。该工具有多种不同的版本来使得比较视图更易于查看：双栏模式、行内模式，甚至是渲染后的 Markdown 模式。团队中的每一个成员都可以选择最适合他们的版本。举例而言，网页视图通常用于查看细微变更，而对于更大的变更，我习惯于使用 vimdiff 或 Meld 在本地浏览。
检查的注释可以整体提交到变更中，也可以提交到指定变更中的个别行中。一些项目限制了行的最大长度，即硬换行，或者一行一句，以使得向文本的特定的部分添加注释更加容易。进一步的变更与注释可以在检查完成接受变更时添加。由于拉取请求在项目仓库以队列形式展示，这是很好的方式来展示目前正在进行的任务以及需要进行检查操作的任务。diff 工具使得评审人员更方便地加入他们的思考。尤其是你在与技术受众工作时，你可以通过他们日常使用的工具获得来自他们的评论。
持续集成与部署
以纯文本形式拥有你的文档的源代码有很多益处，你可以轻易找到每次需要修改的位置，你可以使用现有的诸如 wc、grep或 tree 之类的工具在潜在的大型文档集中工作。当你将这些与源代码管理平台结合起来之后，你可能获得更多的可用工具，并且它们都是开源的。
另一个工作流程上的巨大提升是持续部署的能力。简单来说，这意味着，每当一个拉取请求被合并到主项目中，项目可以直接自动化部署到位。如果变更好到足以接收进项目中，他同时可以在文档页面中实时更新，从而帮助到你的读者。典型情况下，持续部署是配置在任意一台分离的自动化服务器上的，比如 Jenkins 或者 Git Hooks。不论哪种方式，基于文本的标记语言与 Doc as Code 平台(通常是静态网页生成器，比如 Hugo 或 Sphinx)结合来生成文档网站，然后自动部署。
在部署之前，同样的自动化流程可以被用于对将要合并的拉取请求进行检查。在一个编程项目中，通过计算机自行进行代码检查、代码测试和其他的质量检查已经习以为常。通过类似 Vale 之类的工具进行文本检查、文档项目也可以同样对待，你也可以添加其他的工具，比如添加一个链接检查器来确保文中所有的链接都是有效的。
用于文档流程的代码工具
被工程师们熟知并喜爱的工具都是非常好的工具，它们同时也可以用于其他类型的项目中。在文档项目中，它们提升了宝贵的效率，尤其是当你希望你的文档与你的团队同步推进的时候。上面讨论到的所有工具都是开源的，你可以亲自尝试，为大型全球团队部署他们，亦或者介于两者之间，最终使你的成文过程和编程过程一样顺畅。
via: https://opensource.com/article/22/10/docs-as-code
作者：Lorna Mitchell 选题：lkxed 译者：CanYellow 校对：校对者ID