From 46c1c887ee2aaa5dd641c3d03bdbc4a4bcf57f37 Mon Sep 17 00:00:00 2001 From: Xingyu Wang Date: Sat, 22 Apr 2023 17:29:07 +0800 Subject: [PATCH] RP @alim0x https://linux.cn/article-15743-1.html --- ...entation that actually works for your community.md | 57 ++++++++++--------- 1 file changed, 31 insertions(+), 26 deletions(-) rename {translated/tech => published}/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md (65%) diff --git a/translated/tech/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md b/published/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md similarity index 65% rename from translated/tech/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md rename to published/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md index 909698a62c..f9b446d546 100644 --- a/translated/tech/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md +++ b/published/20230316.3 ⭐️⭐️ Write documentation that actually works for your community.md @@ -3,18 +3,22 @@ [#]: author: "Olga Merkulova https://opensource.com/users/olga-merkulova" [#]: collector: "lkxed" [#]: translator: "alim0x" -[#]: reviewer: " " -[#]: publisher: " " -[#]: url: " " +[#]: reviewer: "wxy" +[#]: publisher: "wxy" +[#]: url: "https://linux.cn/article-15743-1.html" 编写对社区真正有用的文档 ====== -成功和可持续的项目，与那些消失无踪的项目有什么不同？答案是——社区。社区是开源项目的发展动力，而文档是构建社区的基石之一。也就是说，文档的意义不仅仅在于文档本身。 +![][0] + +> 建立良好的文档可能是困难的，但它对有效的沟通至关重要。遵循这个框架来编写并与正确的人分享文档。 + +成功和可持续的项目，与那些消失无踪的项目有什么不同？答案是 —— 社区。社区是开源项目的发展动力，而文档是构建社区的基石之一。也就是说，文档的意义不仅仅在于文档本身。 建立好的文档可能很困难。用户不愿意阅读文档，因为它不易查找，它很快就过时了，它冗长，或者它不全面。 -开发团队不写文档，因为他们陷入了“对我来说很明显，所以对所有人都很明显”的陷阱。他们不写，因为他们忙于开发项目。要么是事物发展得太快了，要么是他们开发得还不够快。 +开发团队不写文档，因为他们陷入了“对我来说显而易见，所以对所有人都显而易见”的陷阱。他们不写，因为他们忙于开发项目。要么是需求变化太快了，要么是开发得还不够快。 但是好的文档仍然是团队和项目之间最好的沟通工具。考虑到项目随着时间的推移往往会变得更大，这一点尤其重要。 @@ -35,32 +39,32 @@ 灵活并不意味着混乱。许多项目之所以成功，就是因为它们组织得很好。 -James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到了你目标所在的水平，而是降低到你整个系统所在的水平。”一定要组织好过程，使水平足够高，才能取得成功。 +James Clear（《原子习惯Atomic Habits》一书的作者）写道：“你并不是提升到了你目标所在的水平，而是降低到你整个系统所在的水平。”一定要组织好过程，使水平足够高，才能取得成功。 ### 设计流程 文档本身就是一个项目。你可以把写文档当作写代码一样。事实上，文档可以是一个产品，而且是一个非常有价值的产品。 -这就意味着你可以采用与软件开发相同的流程：分析、需求、设计、实现和维护，把文档作为你的一个流程对待。 +这就意味着你可以采用与软件开发相同的流程：分析、获取需求、设计、实现和维护，把文档作为你的一个流程对待。 -在设计流程时，要从不同的角度考虑。同一份文档不一定适用于所有人。 +在设计流程时，要从不同的角度考虑。不是所有的文档都适用于所有人。 -大多数用户只需要了解项目的概况，而 API 文档则更适合开发者或高级用户。 +大多数用户只需要一个了解项目概况的文档，而 API 文档则是留给开发者或高级用户的。 -开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南和项目与其他软件的架构关系。 +开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南，和项目与其他软件相配合的架构概述。 -![图片展示了编写wenImage demonstrating different perspectives used while documenting.][2] +![图片展示了编写文档时的不同视角][2] 总之，在创建任何流程之前，你必须确定你需要什么： -- **关注的群体：** 包括开发者、集成者、管理员、用户、销售、运营、高管 +- **关注的群体：** 包括开发者、集成商、管理员、用户、销售、运营、高管 - **专业水平：** 要考虑到初级、中级和高级用户 - **详细程度：** 既要有高层级的概述，也要有技术细节，所以要考虑如何呈现这些内容 - **路径和入口：** 人们如何找到文档，如何使用文档 当你思考这些问题时，它可以帮助你构建你想通过文档传达的信息的结构。它定义了文档中必须包含的内容的清晰指标。 -这是如何围绕文档建立一个流程的方法。 +下面是如何围绕文档建立一个流程的方法。 ### 编码约定 @@ -68,7 +72,7 @@ James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到 - 变量命名约定 - 通过使用类、函数命名方案使名称易于理解 -- 避免深度嵌套，或[根本不嵌套][3] +- 避免深度嵌套，或 [根本不嵌套][3] - 不要简单地复制和粘贴代码 - 不应使用长方法 - 避免使用幻数（改用常量） @@ -77,15 +81,15 @@ James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到 ### 开发时测试 -测试不仅仅是关于代码应该如何工作。它还涉及如何使用 API、函数、方法等。编写良好的测试可以揭示基本用例和边缘用例。甚至还有[测试驱动开发][4]的实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的分步场景）。 +测试不仅仅是关于代码应该如何工作。它还涉及如何使用 API、函数、方法等。编写良好的测试可以揭示基本用例和边缘用例。甚至还有一种 [测试驱动开发][4] 的实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的分步场景）。 ### 版本控制 -版本控制（即使是对文档进行版本控制）可以帮助您跟踪更改的逻辑。它可以帮助您回答为什么这么修改。 +版本控制（即使是对文档进行版本控制）可以帮助你跟踪更改的逻辑。它可以帮助你回答为什么这么修改。 -确保提交期间的注释解释为什么进行更改，而不是进行了哪些更改。 +确保提交期间的注释能解释为什么进行更改，而不是进行了哪些更改。 -编写文档过程越吸引人，就会有更多的人参与其中，为它添加创造力和乐趣。您应该通过以下方式考虑文档的可读性： +编写文档过程越吸引人，就会有更多的人参与其中，为它添加创造力和乐趣。你应该通过以下方式考虑文档的可读性： - 软件代码约定 - 图表和图形（也通过文字进行解释） @@ -95,16 +99,16 @@ James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到 - 图片（突出显示重要的部分） - 短视频 -通过使用不同的交流方式，您可以提供更多的方式来参与文档。这有助于防止误解（不同的语言，不同的含义）和有助于通过不同的学习方式进行学习。 +通过使用不同的交流方式，你可以提供更多的方式来参与文档。这有助于防止误解（不同的语言，不同的含义）和有助于通过不同的学习方式进行学习。 以下是一些用于创建文档的软件工具： -- **Javadoc、Doxygen、JsDoc等：** 许多语言都有自动化的文档工具，以帮助捕获代码中的主要功能 +- **Javadoc、Doxygen、JsDoc 等：** 许多语言都有自动化的文档工具，以帮助捕获代码中的主要功能 - **Web 钩子和 CI/CD 引擎：** 允许持续发布文档 -- **Restructured Text，Markdown，Asciidoc：** 文件格式和处理引擎，帮助您从纯文本文件中生成美观且实用的文档 +- **Restructured Text、Markdown、Asciidoc：** 文件格式和处理引擎，帮助你从纯文本文件中生成美观且实用的文档 - **ReadTheDocs：** 是一个可以和公共 Git 存储库联动的文档托管主机 -- **Draw.io， LibreOffice Draw，Dia：** 制作图表，图形，思维导图，路线图，计划，标准和指标等 -- **Peek，Asciinema：** 记录终端命令操作 +- **Draw.io、LibreOffice Draw、Dia：** 制作图表、图形、思维导图、路线图、计划、标准和指标等 +- **Peek、Asciinema：** 记录终端命令操作 - **VokoscreenNG：** 录制屏幕和鼠标点击操作 ### 文档很重要 @@ -117,7 +121,7 @@ James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到 要将这个过程视为一个连续的整体，并在其中融合使用沟通、流程和文档的方式。 -![图片展示了文档作为一种沟通的过程。][5] +![图片展示了文档作为一种沟通的过程][5] 文档是一种沟通手段。 @@ -128,7 +132,7 @@ via: https://opensource.com/article/23/3/community-documentation 作者：[Olga Merkulova][a] 选题：[lkxed][b] 译者：[alim0x](https://github.com/alim0x) -校对：[校对者ID](https://github.com/校对者ID) +校对：[wxy](https://github.com/wxy) 本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出 @@ -138,4 +142,5 @@ via: https://opensource.com/article/23/3/community-documentation [2]: https://opensource.com/sites/default/files/2023-03/different.perspectives.whiledocumenting.png [3]: https://opensource.com/article/20/2/java-streams [4]: https://opensource.com/article/20/1/test-driven-development -[5]: https://opensource.com/sites/default/files/2023-03/doc.is_.aprocessofcommunication.png \ No newline at end of file +[5]: https://opensource.com/sites/default/files/2023-03/doc.is_.aprocessofcommunication.png +[0]: https://img.linux.net.cn/data/attachment/album/202304/22/172758mm2rzjry2ful090y.jpg \ No newline at end of file