TranslateProject/published/202212/20221028.1 ⭐️⭐️ Write documentation like you develop code.md

[#]: subject: "Write documentation like you develop code"
[#]: via: "https://opensource.com/article/22/10/docs-as-code"
[#]: author: "Lorna Mitchell https://opensource.com/users/lornajane"
[#]: collector: "lkxed"
[#]: translator: "CanYellow"
[#]: reviewer: "wxy"
[#]: publisher: "wxy"
[#]: url: "https://linux.cn/article-15364-1.html"

像书写代码一样撰写文档
======

![][0]

> 不想让文档成为事后的想法？或许你该尝试一下全新的写作方式。

很多工程师与手工艺者都对他们使用的工具有特别的要求。为了顺利的完成工作，你需要最好的工具和使用它们的技巧。软件开发中最好的工具在应用到其他的数字创作领域中也可以是很强大的。<ruby>[文档即代码][1]<rt>Docs as Code</rt></ruby> 的方式就是很好的例子。“文档即代码”意味着使用与代码开发相同的工具和工作流来撰写文档。文档即代码的支持者认为，这样的方式可以在降低写作者的工作量的同时，也带来了更好的文档。

### 文本格式与源文件控制

从传统的写作平台切换到文档即代码方式时，最主要的调整是将写作内容保存在基于文本的标记格式中。这一转变使得基于纯文本的工具都适用于文档写作。无论你选择 [DocBook][2]、[Markdown][3] 或者其他的标记语言，从只使用一种工具到使用一种标准格式配合多种工具是一种巨大的转变。

找到支持你的工作流程的工具是非常重要的。很多开发者在文档即代码项目中使用他们的 [代码编辑器][4]。因为他们已经是这些工具的高阶用户，一切都很顺利。而找到适合团队里其他专业人员，比如技术撰稿、编辑、信息架构师和文档产品责任人的工具可能需要一番努力。这里有一些选项可供参考：

- 各种 [优秀的 Markdown 编辑器][5] 之一
- 附带良好的预览工具的代码编辑器可能更适合非程序员
- 流行的 Git 托管服务的网页界面尤其适用于偶尔有需要的贡献者

一旦内容以标记语言的格式安全地保存，就可以使用 [Git][6] 这样的版本控制进行管理。Git 相比大多数文档平台具有更多的功能：

- 清晰详细的文档版本历史：谁在什么时候改变了什么。如果你有良好的提交信息惯例，你甚至可以了解到为什么会有这样的变更。
- 简明的并行修改过程。在 Git 中使用分支工作意味着任何人可以做出他们想要的任何改变，并在最后合并所做的变更。
- 先进的协作与审查工具。所有的源代码管理平台都被设计成支持详细审查每一个变更，并根据需要进行讨论，使每个人都确信这个变更可以继续进行。
- 自动质量检查，比如拼写检查和链接检查。这不仅节省了时间，而且可以发现可能遗漏的错误。

源代码管理有很多优点。但要记住，如果你准备入门源代码管理，它有一定的学习曲线。这是一些有助于撰写者入门的优秀的 [学习资源][7] 和 [文章][8]。你也可以让具有好奇心的文档撰写者自行寻找对他们有用的学习材料，而不是请你的工程师来培训他们。（问我是怎么学会的？ —— 当然是通过艰苦的方式！）

### 拉取请求和评审循环

所有的源代码管理平台都围绕 <ruby>拉取请求<rt>Pull Request</rt></ruby> 这一概念设计的，这有时也称为 <rbuy>合并请求<rt>Merge Request</rt></ruby>：有时候，某个人或某个团队先将一系列改变整合到一起，然后请求把这些修改拉到主项目中。不过从许多方面来说，在文档中一次处理多个变更比在代码中更容易。改变一篇文章中的某个地方，比更改代码并发现有其它几个地方依赖它，副作用更小。

最强大的协作工具是 [diff][9]，它可以通过一个易于理解的方式展示旧版本与新版本之间的差异。该工具有许多不同的版本，可以使比较视图更易于查看：双栏模式、行内模式，甚至是渲染过的 Markdown 模式。团队中的每一个成员都可以选择最适合他们的工具。举例而言，网页视图通常用于查看细微变更，而对于更大的变更，我习惯于使用 `vimdiff` 或 [Meld][10] 在本地浏览。

评审意见可以被添加到整个修改中，也可以添加到拟议的变更的个别行中。一些项目限制了行的最大长度，即硬换行，或者一行一句，以使得向文本的特定的部分添加注释更加容易。可以添加进一步的修改与评论，直到审查过程结束，修改被接受。由于拉取请求在项目仓库以队列形式展示，这是一种很好的方式，可以展示目前正在进行的任务以及需要进行检查操作的任务。`diff` 工具使得评审人员更方便地添加他们的思考。尤其是你在与技术受众工作时，你可以通过他们日常使用的工具获得来自他们的评论。

### 持续集成与部署

以纯文本形式提供你的文档的源代码有很多益处，你可以轻易找到每一个需要修改的位置，你可以使用现有的诸如 [wc][11]、[grep][12] 或 `tree` 之类的工具，来处理潜在的大型文档集。当你将这些与源代码管理平台结合起来之后，你可能获得更多的可用工具，并且它们都是开源的。

另一个工作流程上的巨大提升是持续部署的能力。简单来说，这意味着，每当一个拉取请求被合并到主项目中，项目可以直接自动化部署到位。如果这个变更足够好，就可以放进项目中，它也足够好到可以在放到文档网站上帮助你的读者。典型情况下，持续部署是配置在一台单独的自动化服务器上的，比如 [Jenkins][13] 或者 [Git 钩子][14]。不论哪种方式，基于文本的标记语言与文档即代码平台（通常是静态网页生成器，比如 [Hugo][15] 或 [Sphinx][16]）结合来生成文档网站，然后自动部署。

在部署之前，同样的自动化流程可以被用于对将要合并的拉取请求进行检查。在一个编程项目中，通过计算机自行进行代码检查、代码测试和其他的质量检查已经习以为常。通过类似 [Vale][17] 之类的工具可以对文本进行检查，文档项目也可以同样对待。你也可以添加其他的工具，比如添加一个链接检查器来确保文中所有的链接都是有效的。

### 用于文档流程的代码工具

被工程师们熟知并喜爱的工具都是非常好的工具，它们同时也可以用于其他类型的项目中。对于文档而言，它们提升了宝贵的效率，尤其是当你希望你的文档与你的团队同步推进的时候。上面讨论到的所有工具都是开源的，你可以亲自尝试，也可以为大型全球团队，亦或者介于两者之间的团队，部署它们。愿你的成文过程和编程过程一样顺畅。

--------------------------------------------------------------------------------

via: https://opensource.com/article/22/10/docs-as-code

作者：[Lorna Mitchell][a]
选题：[lkxed][b]
译者：[CanYellow](https://github.com/CanYellow)
校对：[wxy](https://github.com/wxy)

本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出

[a]: https://opensource.com/users/lornajane
[b]: https://github.com/lkxed
[1]: https://www.writethedocs.org/guide/docs-as-code
[2]: https://opensource.com/article/17/9/docbook
[3]: http://commonmark.org
[4]: https://opensource.com/article/20/12/eclipse
[5]: https://opensource.com/article/21/10/markdown-editors
[6]: https://opensource.com/downloads/cheat-sheet-git
[7]: https://opensource.com/article/18/1/step-step-guide-git
[8]: https://opensource.com/article/19/4/write-git
[9]: https://opensource.com/article/21/11/linux-diff-patch
[10]: https://opensource.com/article/20/3/meld
[11]: https://www.redhat.com/sysadmin/linux-wc-command?intcmp=7013a000002qLH8AAM
[12]: https://opensource.com/downloads/grep-cheat-sheet
[13]: https://www.jenkins.io
[14]: https://www.redhat.com/sysadmin/git-hooks
[15]: https://opensource.com/article/18/3/start-blog-30-minutes-hugo
[16]: https://opensource.com/article/19/11/document-python-sphinx
[17]: https://vale.sh
[0]: https://img.linux.net.cn/data/attachment/album/202212/19/215600m3bzhqlu23lskssl.jpg
RP @CanYellow https://linux.cn/article-15364-1.html 2022-12-19 21:59:00 +08:00			`[#]: subject: "Write documentation like you develop code"`
			`[#]: via: "https://opensource.com/article/22/10/docs-as-code"`
			`[#]: author: "Lorna Mitchell https://opensource.com/users/lornajane"`
			`[#]: collector: "lkxed"`
			`[#]: translator: "CanYellow"`
			`[#]: reviewer: "wxy"`
			`[#]: publisher: "wxy"`
			`[#]: url: "https://linux.cn/article-15364-1.html"`

			`像书写代码一样撰写文档`
			`======`

			`![][0]`

			`> 不想让文档成为事后的想法？或许你该尝试一下全新的写作方式。`

			很多工程师与手工艺者都对他们使用的工具有特别的要求。为了顺利的完成工作，你需要最好的工具和使用它们的技巧。软件开发中最好的工具在应用到其他的数字创作领域中也可以是很强大的。<ruby>[文档即代码][1]<rt>Docs as Code</rt></ruby> 的方式就是很好的例子。“文档即代码”意味着使用与代码开发相同的工具和工作流来撰写文档。文档即代码的支持者认为，这样的方式可以在降低写作者的工作量的同时，也带来了更好的文档。

			`### 文本格式与源文件控制`

			`从传统的写作平台切换到文档即代码方式时，最主要的调整是将写作内容保存在基于文本的标记格式中。这一转变使得基于纯文本的工具都适用于文档写作。无论你选择 [DocBook][2]、[Markdown][3] 或者其他的标记语言，从只使用一种工具到使用一种标准格式配合多种工具是一种巨大的转变。`

			`找到支持你的工作流程的工具是非常重要的。很多开发者在文档即代码项目中使用他们的 [代码编辑器][4]。因为他们已经是这些工具的高阶用户，一切都很顺利。而找到适合团队里其他专业人员，比如技术撰稿、编辑、信息架构师和文档产品责任人的工具可能需要一番努力。这里有一些选项可供参考：`

			`- 各种 [优秀的 Markdown 编辑器][5] 之一`
			`- 附带良好的预览工具的代码编辑器可能更适合非程序员`
			`- 流行的 Git 托管服务的网页界面尤其适用于偶尔有需要的贡献者`

			`一旦内容以标记语言的格式安全地保存，就可以使用 [Git][6] 这样的版本控制进行管理。Git 相比大多数文档平台具有更多的功能：`

			`- 清晰详细的文档版本历史：谁在什么时候改变了什么。如果你有良好的提交信息惯例，你甚至可以了解到为什么会有这样的变更。`
			`- 简明的并行修改过程。在 Git 中使用分支工作意味着任何人可以做出他们想要的任何改变，并在最后合并所做的变更。`
			`- 先进的协作与审查工具。所有的源代码管理平台都被设计成支持详细审查每一个变更，并根据需要进行讨论，使每个人都确信这个变更可以继续进行。`
			`- 自动质量检查，比如拼写检查和链接检查。这不仅节省了时间，而且可以发现可能遗漏的错误。`

			`源代码管理有很多优点。但要记住，如果你准备入门源代码管理，它有一定的学习曲线。这是一些有助于撰写者入门的优秀的 [学习资源][7] 和 [文章][8]。你也可以让具有好奇心的文档撰写者自行寻找对他们有用的学习材料，而不是请你的工程师来培训他们。（问我是怎么学会的？ —— 当然是通过艰苦的方式！）`

			`### 拉取请求和评审循环`

			所有的源代码管理平台都围绕 <ruby>拉取请求<rt>Pull Request</rt></ruby> 这一概念设计的，这有时也称为 <rbuy>合并请求<rt>Merge Request</rt></ruby>：有时候，某个人或某个团队先将一系列改变整合到一起，然后请求把这些修改拉到主项目中。不过从许多方面来说，在文档中一次处理多个变更比在代码中更容易。改变一篇文章中的某个地方，比更改代码并发现有其它几个地方依赖它，副作用更小。

			最强大的协作工具是 [diff][9]，它可以通过一个易于理解的方式展示旧版本与新版本之间的差异。该工具有许多不同的版本，可以使比较视图更易于查看：双栏模式、行内模式，甚至是渲染过的 Markdown 模式。团队中的每一个成员都可以选择最适合他们的工具。举例而言，网页视图通常用于查看细微变更，而对于更大的变更，我习惯于使用 `vimdiff` 或 [Meld][10] 在本地浏览。

			评审意见可以被添加到整个修改中，也可以添加到拟议的变更的个别行中。一些项目限制了行的最大长度，即硬换行，或者一行一句，以使得向文本的特定的部分添加注释更加容易。可以添加进一步的修改与评论，直到审查过程结束，修改被接受。由于拉取请求在项目仓库以队列形式展示，这是一种很好的方式，可以展示目前正在进行的任务以及需要进行检查操作的任务。`diff` 工具使得评审人员更方便地添加他们的思考。尤其是你在与技术受众工作时，你可以通过他们日常使用的工具获得来自他们的评论。

			`### 持续集成与部署`

			以纯文本形式提供你的文档的源代码有很多益处，你可以轻易找到每一个需要修改的位置，你可以使用现有的诸如 [wc][11]、[grep][12] 或 `tree` 之类的工具，来处理潜在的大型文档集。当你将这些与源代码管理平台结合起来之后，你可能获得更多的可用工具，并且它们都是开源的。

			另一个工作流程上的巨大提升是持续部署的能力。简单来说，这意味着，每当一个拉取请求被合并到主项目中，项目可以直接自动化部署到位。如果这个变更足够好，就可以放进项目中，它也足够好到可以在放到文档网站上帮助你的读者。典型情况下，持续部署是配置在一台单独的自动化服务器上的，比如 [Jenkins][13] 或者 [Git 钩子][14]。不论哪种方式，基于文本的标记语言与文档即代码平台（通常是静态网页生成器，比如 [Hugo][15] 或 [Sphinx][16]）结合来生成文档网站，然后自动部署。

			`在部署之前，同样的自动化流程可以被用于对将要合并的拉取请求进行检查。在一个编程项目中，通过计算机自行进行代码检查、代码测试和其他的质量检查已经习以为常。通过类似 [Vale][17] 之类的工具可以对文本进行检查，文档项目也可以同样对待。你也可以添加其他的工具，比如添加一个链接检查器来确保文中所有的链接都是有效的。`

			`### 用于文档流程的代码工具`

			`被工程师们熟知并喜爱的工具都是非常好的工具，它们同时也可以用于其他类型的项目中。对于文档而言，它们提升了宝贵的效率，尤其是当你希望你的文档与你的团队同步推进的时候。上面讨论到的所有工具都是开源的，你可以亲自尝试，也可以为大型全球团队，亦或者介于两者之间的团队，部署它们。愿你的成文过程和编程过程一样顺畅。`

			`--------------------------------------------------------------------------------`

			`via: https://opensource.com/article/22/10/docs-as-code`

			`作者：[Lorna Mitchell][a]`
			`选题：[lkxed][b]`
			`译者：[CanYellow](https://github.com/CanYellow)`
			`校对：[wxy](https://github.com/wxy)`

			`本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出`

			`[a]: https://opensource.com/users/lornajane`
			`[b]: https://github.com/lkxed`
			`[1]: https://www.writethedocs.org/guide/docs-as-code`
			`[2]: https://opensource.com/article/17/9/docbook`
			`[3]: http://commonmark.org`
			`[4]: https://opensource.com/article/20/12/eclipse`
			`[5]: https://opensource.com/article/21/10/markdown-editors`
			`[6]: https://opensource.com/downloads/cheat-sheet-git`
			`[7]: https://opensource.com/article/18/1/step-step-guide-git`
			`[8]: https://opensource.com/article/19/4/write-git`
			`[9]: https://opensource.com/article/21/11/linux-diff-patch`
			`[10]: https://opensource.com/article/20/3/meld`
			`[11]: https://www.redhat.com/sysadmin/linux-wc-command?intcmp=7013a000002qLH8AAM`
			`[12]: https://opensource.com/downloads/grep-cheat-sheet`
			`[13]: https://www.jenkins.io`
			`[14]: https://www.redhat.com/sysadmin/git-hooks`
			`[15]: https://opensource.com/article/18/3/start-blog-30-minutes-hugo`
			`[16]: https://opensource.com/article/19/11/document-python-sphinx`
			`[17]: https://vale.sh`
			`[0]: https://img.linux.net.cn/data/attachment/album/202212/19/215600m3bzhqlu23lskssl.jpg`