From d87856982277770a41cdb6ebb2e0ab0898aaffda Mon Sep 17 00:00:00 2001
From: Xingyu Wang <xingyu.wang@gmail.com>
Date: Mon, 19 Dec 2022 21:59:00 +0800
Subject: [PATCH] RP

@CanYellow
https://linux.cn/article-15364-1.html
---
 ...­�ï¸� Write documentation like you develop code.md | 88 +++++++++++++++++++
 ...­�ï¸� Write documentation like you develop code.md | 86 ------------------
 2 files changed, 88 insertions(+), 86 deletions(-)
 create mode 100644 published/20221028.1 ���� Write documentation like you develop code.md
 delete mode 100644 translated/talk/20221028.1 ���� Write documentation like you develop code.md

diff --git a/published/20221028.1 ���� Write documentation like you develop code.md b/published/20221028.1 ���� Write documentation like you develop code.md
new file mode 100644
index 0000000000..95f0e82e50
--- /dev/null
+++ b/published/20221028.1 ���� Write documentation like you develop code.md	
@@ -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
\ No newline at end of file
diff --git a/translated/talk/20221028.1 ���� Write documentation like you develop code.md b/translated/talk/20221028.1 ���� Write documentation like you develop code.md
deleted file mode 100644
index 9c373f96bd..0000000000
--- a/translated/talk/20221028.1 ���� Write documentation like you develop code.md	
+++ /dev/null
@@ -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