document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-01-13 22:30:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #28275 from wxy/20221028.1-⭐️⭐️-Write-documentation-like-you-develop-code

Browse Source 
RP:published/20221028.1 ⭐️⭐️ Write documentation like you develop code.md
This commit is contained in:
Xingyu.Wang 2022-12-19 22:09:40 +08:00 committed by GitHub
commit c40911f638
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 88 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
published/20221028.1 ⭐️⭐️ Write documentation like you develop code.md Normal file
View File

@ -0,0 +1,88 @@
[#]: 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

86
translated/talk/20221028.1 ⭐️⭐️ Write documentation like you develop code.md
View File

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