mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
Merge pull request #29129 from alim0x/translating
[translated]Write documentation that actually works for your community
This commit is contained in:
Xingyu.Wang
GitHub
commit
cf21723d61
@ -1,141 +0,0 @@
|
||||
[#]: subject: "Write documentation that actually works for your community"
|
||||
[#]: via: "https://opensource.com/article/23/3/community-documentation"
|
||||
[#]: author: "Olga Merkulova https://opensource.com/users/olga-merkulova"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "alim0x"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
Write documentation that actually works for your community
|
||||
======
|
||||
|
||||
What distinguishes successful and sustainable projects from those that disappeared into the void? Spoiler — it's community. Community is what drives an open source project, and documentation is one of the foundational blocks for building a community. In other words, documentation isn't only about documentation.
|
||||
|
||||
Establishing good documentation can be difficult, though. Users don't read documentation because it's inconvenient, it goes out of date very quickly, there's too much, or there's not enough.
|
||||
|
||||
The development team doesn't write documentation because of the "it's obvious for me, so it's obvious to everyone" trap. They don't write because they are too busy making the project exist. Things are developing too fast, or they're not developing fast enough.
|
||||
|
||||
But good documentation remains the best communication tool for groups and projects. This is especially true considering that projects tend to get bigger over time.
|
||||
|
||||
Documentation can be a single source of truth within a group or a company. This is important when coordinating people toward a common goal and preserving knowledge as people move on to different projects.
|
||||
|
||||
So how do you write appropriate documentation for a project and share it with the right people?
|
||||
|
||||
### What is successful community documentation?
|
||||
|
||||
To succeed in writing documentation in your community:
|
||||
|
||||
- Organize your routine
|
||||
- Make it clear and straightforward
|
||||
- Be flexible, make changes to the routine according to a specific situation
|
||||
- Do version control
|
||||
|
||||
![Image demonstrating the flow of documentation.][1]
|
||||
|
||||
Being flexible doesn't mean being chaotic. Many projects have succeeded just because they are well-organized.
|
||||
|
||||
James Clear (author of _Atomic Habits_) wrote, "You do not rise to the level of your goals. You fall to the level of your systems." Be sure to organize the process so that the level is high enough to achieve success.
|
||||
|
||||
### Design the process
|
||||
|
||||
Documentation is a project. Think of writing docs as writing code. In fact, documentation can be a product and a very useful one at that.
|
||||
|
||||
This means you can use the same processes as in software development: analysis, capturing requirements, design, implementation, and maintenance. Make documentation one of your processes.
|
||||
|
||||
Think about it from different perspectives while designing the process. Not all documentation is the right documentation for everyone.
|
||||
|
||||
Most users only need a high-level overview of a project, while API documentation is probably best reserved for developers or advanced users.
|
||||
|
||||
Developers need library and function documentation. Users are better served by example use cases, step-by-step guides, and an architectural overview of how a project fits in with the other software they use.
|
||||
|
||||
![Image demonstrating different perspectives used while documenting.][2]
|
||||
|
||||
Ultimately, before creating any process, you must determine what you need:
|
||||
|
||||
- **Focus groups:** this includes developers, integrators, administrators, users, sales, operations, executives
|
||||
- **Level of expertise**: Keep in mind the beginner, intermediate, and advanced users
|
||||
- **Level of detail**: There's room for a high-level overview as well as technical detail, so consider how you want these to be presented
|
||||
- **Journeys and entry points**: How do people find the documentation, how they use it
|
||||
|
||||
When you ponder these questions, it helps you structure information you want to communicate through documentation. It defines clear metrics on what has to be in the documentation.
|
||||
|
||||
Here's how to approach building a process around documentation.
|
||||
|
||||
### Coding conventions
|
||||
|
||||
The code itself should make sense. Documentation should be expressed through good class names, file names, and so on. Create common coding standards and make a self-documented code process by thinking about:
|
||||
|
||||
- Variable naming conventions
|
||||
- Make names understandable by using class, function naming schemes
|
||||
- Avoid deep nesting, or [don't nest at all][3]
|
||||
- Do not simply copy-and-paste code
|
||||
- No long methods should be used
|
||||
- Avoid using magic numbers (use const instead)
|
||||
- Use extract methods, variables, and so on
|
||||
- Use meaningful directory structures, modules, packages, and files
|
||||
|
||||
### Testing along with engineering
|
||||
|
||||
Testing isn't only about how code should behave. It's also about how to use an API, functions, methods, and so on. Well-written tests can reveal base and edge case scenarios. There's even a [test-driven development][4] practice that focuses on creating test cases (step by step scenarios of what should be tested and how) before code development.
|
||||
|
||||
### Version control
|
||||
|
||||
Version control, even for your documentation, helps you track the logic of your changes. It can help you answer why a change was made.
|
||||
|
||||
Make sure comments during commits explain WHY a change was made, not WHAT change was made.
|
||||
|
||||
The more engaging the documentation process is, the more people will get into it. Add creativity and fun to it. You should think about readability of documentation by using:
|
||||
|
||||
- software code conventions
|
||||
- diagrams and graphs (that are also explained in text)
|
||||
- mind maps
|
||||
- concept maps
|
||||
- infographics
|
||||
- images (highlight important parts)
|
||||
- short videos
|
||||
|
||||
By using different ways of communication, you offer more ways to engage with your documentation. This can help forestall misunderstanding (different languages, different meanings), and different learning styles.
|
||||
|
||||
Here are some software tools for creating documentation:
|
||||
|
||||
- **Javadoc, Doxygen, JsDoc, and so on**: Many languages have automated documentation tools to help capture major features in code
|
||||
- **Web hooks and CI/CD engines**: Allows continuous publication of your documentation
|
||||
- **Restructured Text, Markdown, Asciidoc**: File formats and processing engines help you produce beautiful and usable documentation out of plain text files
|
||||
- **ReadTheDocs**_:_ Is a documentation host that can be attached to a public Git repository
|
||||
- **Draw.io_,__LibreOffice Draw,__Dia_**: Produce diagrams, graphs, mind-maps, roadmaps, planning, standards, and metrics
|
||||
- **Peek_,_Asciinema**: Use commands for recording your terminal
|
||||
- **VokoscreenNG**: Use mouse clicks and screen capture
|
||||
|
||||
### Documentation is vital
|
||||
|
||||
Documenting processes and protocols are just as important as documenting your project itself. Most importantly, make information about your project and creation of your project exciting.
|
||||
|
||||
The speed of entering into a project and process, and understanding how everything works, is an important feature. It helps ensure continued engagement. Simple processes and a clear understanding of what needs to be done is obtained by building one "language" in the team.
|
||||
|
||||
Documentation is designed to convey value, which means demonstrating something through words and deeds. It doesn't matter whether it's a member of your team or a user of your application.
|
||||
|
||||
Think about the process as a continuum and use means of communication, processes, and documentation.
|
||||
|
||||
![Image showing documentation as a process of communication.][5]
|
||||
|
||||
Documentation is a means of communication.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/23/3/community-documentation
|
||||
|
||||
作者：[Olga Merkulova][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/olga-merkulova
|
||||
[b]: https://github.com/lkxed/
|
||||
[1]: https://opensource.com/sites/default/files/2023-03/documentationflowchart.png
|
||||
[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
|
||||
@ -0,0 +1,141 @@
|
||||
[#]: subject: "Write documentation that actually works for your community"
|
||||
[#]: via: "https://opensource.com/article/23/3/community-documentation"
|
||||
[#]: author: "Olga Merkulova https://opensource.com/users/olga-merkulova"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "alim0x"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
编写对社区真正有用的文档
|
||||
======
|
||||
|
||||
成功和可持续的项目，与那些消失无踪的项目有什么不同？答案是——社区。社区是开源项目的发展动力，而文档是构建社区的基石之一。也就是说，文档的意义不仅仅在于文档本身。
|
||||
|
||||
建立好的文档可能很困难。用户不愿意阅读文档，因为它不易查找，它很快就过时了，它冗长，或者它不全面。
|
||||
|
||||
开发团队不写文档，因为他们陷入了“对我来说很明显，所以对所有人都很明显”的陷阱。他们不写，因为他们忙于开发项目。要么是事物发展得太快了，要么是他们开发得还不够快。
|
||||
|
||||
但是好的文档仍然是团队和项目之间最好的沟通工具。考虑到项目随着时间的推移往往会变得更大，这一点尤其重要。
|
||||
|
||||
文档可以是团队或公司内部的唯一真理。这在协调人们朝着共同的目标前进，以及在人们转移到不同的项目时保留知识方面非常重要。
|
||||
|
||||
那么，要如何为一个项目写出合适的文档，并与正确的人分享呢？
|
||||
|
||||
### 什么是成功的社区文档？
|
||||
|
||||
要想在你的社区文档编写中取得成功，你需要：
|
||||
|
||||
- 规划你的路径
|
||||
- 使其清晰简单
|
||||
- 灵活变通，根据具体情况调整路径
|
||||
- 做版本控制
|
||||
|
||||
![图片展示了建立文档的整个流程][1]
|
||||
|
||||
灵活并不意味着混乱。许多项目之所以成功，就是因为它们组织得很好。
|
||||
|
||||
James Clear（_《原子习惯》_ 的作者）写道：“你并不是提升到了你目标所在的水平，而是降低到你整个系统所在的水平。”一定要组织好过程，使水平足够高，才能取得成功。
|
||||
|
||||
### 设计流程
|
||||
|
||||
文档本身就是一个项目。你可以把写文档当作写代码一样。事实上，文档可以是一个产品，而且是一个非常有价值的产品。
|
||||
|
||||
这就意味着你可以采用与软件开发相同的流程：分析、需求、设计、实现和维护，把文档作为你的一个流程对待。
|
||||
|
||||
在设计流程时，要从不同的角度考虑。同一份文档不一定适用于所有人。
|
||||
|
||||
大多数用户只需要了解项目的概况，而 API 文档则更适合开发者或高级用户。
|
||||
|
||||
开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南和项目与其他软件的架构关系。
|
||||
|
||||
![图片展示了编写wenImage demonstrating different perspectives used while documenting.][2]
|
||||
|
||||
总之，在创建任何流程之前，你必须确定你需要什么：
|
||||
|
||||
- **关注的群体：** 包括开发者、集成者、管理员、用户、销售、运营、高管
|
||||
- **专业水平：** 要考虑到初级、中级和高级用户
|
||||
- **详细程度：** 既要有高层级的概述，也要有技术细节，所以要考虑如何呈现这些内容
|
||||
- **路径和入口：** 人们如何找到文档，如何使用文档
|
||||
|
||||
当你思考这些问题时，它可以帮助你构建你想通过文档传达的信息的结构。它定义了文档中必须包含的内容的清晰指标。
|
||||
|
||||
这是如何围绕文档建立一个流程的方法。
|
||||
|
||||
### 编码约定
|
||||
|
||||
代码本身应该有意义。文档应通过良好的类名、文件名等来表达出来。通过思考以下内容，创建通用的编码标准和自我注解的编码过程：
|
||||
|
||||
- 变量命名约定
|
||||
- 通过使用类、函数命名方案使名称易于理解
|
||||
- 避免深度嵌套，或[根本不嵌套][3]
|
||||
- 不要简单地复制和粘贴代码
|
||||
- 不应使用长方法
|
||||
- 避免使用幻数（改用常量）
|
||||
- 使用提取的方法、变量等
|
||||
- 使用有意义的目录结构、模块、包和文件名
|
||||
|
||||
### 开发时测试
|
||||
|
||||
测试不仅仅是关于代码应该如何工作。它还涉及如何使用 API、函数、方法等。编写良好的测试可以揭示基本用例和边缘用例。甚至还有[测试驱动开发][4]的实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的分步场景）。
|
||||
|
||||
### 版本控制
|
||||
|
||||
版本控制（即使是对文档进行版本控制）可以帮助您跟踪更改的逻辑。它可以帮助您回答为什么这么修改。
|
||||
|
||||
确保提交期间的注释解释为什么进行更改，而不是进行了哪些更改。
|
||||
|
||||
编写文档过程越吸引人，就会有更多的人参与其中，为它添加创造力和乐趣。您应该通过以下方式考虑文档的可读性：
|
||||
|
||||
- 软件代码约定
|
||||
- 图表和图形（也通过文字进行解释）
|
||||
- 思维导图
|
||||
- 概念图
|
||||
- 信息图表
|
||||
- 图片（突出显示重要的部分）
|
||||
- 短视频
|
||||
|
||||
通过使用不同的交流方式，您可以提供更多的方式来参与文档。这有助于防止误解（不同的语言，不同的含义）和有助于通过不同的学习方式进行学习。
|
||||
|
||||
以下是一些用于创建文档的软件工具：
|
||||
|
||||
- **Javadoc、Doxygen、JsDoc等：** 许多语言都有自动化的文档工具，以帮助捕获代码中的主要功能
|
||||
- **Web 钩子和 CI/CD 引擎：** 允许持续发布文档
|
||||
- **Restructured Text，Markdown，Asciidoc：** 文件格式和处理引擎，帮助您从纯文本文件中生成美观且实用的文档
|
||||
- **ReadTheDocs：** 是一个可以和公共 Git 存储库联动的文档托管主机
|
||||
- **Draw.io， LibreOffice Draw，Dia：** 制作图表，图形，思维导图，路线图，计划，标准和指标等
|
||||
- **Peek，Asciinema：** 记录终端命令操作
|
||||
- **VokoscreenNG：** 录制屏幕和鼠标点击操作
|
||||
|
||||
### 文档很重要
|
||||
|
||||
编写文档的过程和协议与项目本身同样重要。最重要的是，它把项目的信息和项目的创造传达到位，更加令人兴奋。
|
||||
|
||||
快速进入项目和流程，以及了解一切是如何工作的，是文档一个重要的功能。它有助于确保众人持续参与。通过在团队中构建一种“语言”，可以简化流程，更清晰地理解所要做的事情。
|
||||
|
||||
文档旨在传达价值，即无论是通过团队成员还是通过应用程序的用户的言行，来展示出某些东西。
|
||||
|
||||
要将这个过程视为一个连续的整体，并在其中融合使用沟通、流程和文档的方式。
|
||||
|
||||
![图片展示了文档作为一种沟通的过程。][5]
|
||||
|
||||
文档是一种沟通手段。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/23/3/community-documentation
|
||||
|
||||
作者：[Olga Merkulova][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[alim0x](https://github.com/alim0x)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/olga-merkulova
|
||||
[b]: https://github.com/lkxed/
|
||||
[1]: https://opensource.com/sites/default/files/2023-03/documentationflowchart.png
|
||||
[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
|
||||
Loading…
Reference in New Issue
Block a user