跳转至

Read, Find, Fix！成为香山文档守护者！「文档捉虫大作战」第一期

你是否曾在使用开源项目时，被一份“天书”般的文档劝退？又或者，你火眼金睛，总能发现文档中的“小秘密”？现在，你的机会来了！香山社区正式启动「文档捉虫大作战」第一期，邀请所有热爱开源、乐于探索的你，一起为香山文档“找茬”，共同提升文档质量！

💡 为什么我们要“捉虫”？

一份清晰、准确、易懂的文档，是开源项目蓬勃发展的基石。它能帮助新用户快速上手，也能让资深开发者更高效地理解项目细节。本次活动，我们希望：

1.提升文档可读性与准确性：发现并优化文档中模糊、错误或过时的内容。 2.鼓励社区深度参与：让更多人通过阅读文档，深入了解香山项目，并积极参与到社区贡献中来。

🎯 谁能参与？

无论你是：

  • 开源社区的开发者、用户、文档贡献者
  • 对香山项目感兴趣的技术爱好者
  • 甚至是初次接触开源，但愿意阅读文档的新手

我们都张开双臂欢迎你！无需经验，只要你有一颗“找茬”的心！

🗓️ 活动时间

2025 年 9 月 15 日 — 2025 年 10 月 31 日

活动进展与最终结果将在 香山社区网站 公布，敬请关注！

📚 捉虫目标文档

本期活动主要针对以下香山开源项目的中文和英文文档：

📝 如何参与“捉虫”？

参与流程非常简单，只需几步，你就能成为香山文档的“守护者”！

1. 了解文档

请仔细阅读上述列出的相关文档，熟悉其内容和结构。建议您选择自己感兴趣或擅长的部分进行深入阅读，以便更好地发现潜在问题。

2. 认领任务

为了避免参与者的审阅范围产生重叠，本次活动采用先认领任务再提交贡献的模式。

在开始捉虫前，请浏览任务清单，找到自己的希望认领的任务文档，如 docs/zh/introduction.md，随后在 Issue 下评论：

/claim docs/zh/introduction.md

随后，机器人会自动将认领者的用户名加入文档列表中。同一个任务可以被多人认领，我们仍然建议您优先选择未被认领的文档。

如果您误认领了某任务文档，如 docs/zh/introduction.md，可以在 Issue 下评论如下命令取消认领：

/unclaim docs/zh/introduction.md

3. 发现问题

在认领任务后，您就可以开始查找文档中的问题了，下面是一些典型的错误：

  • 表述模糊或难以理解：文字描述不清晰，导致读者难以理解其含义。
  • 技术错误或过时信息：文档中包含不准确的技术细节、代码示例错误或已过时的信息。
  • 缺少关键说明或示例：某些概念或操作缺乏必要的解释或实际示例。
  • 格式排版问题：文档布局混乱、排版不规范、图片缺失或显示，例如文档中出现了未被渲染的标识符、图片表格缺少标题、图片显示异常、排版格式混乱等
  • 错别字：文字拼写错误、语法错误或标点符号使用不当。
  • 翻译问题：译文与原文存在偏差、专有名词未被正确翻译等。
  • 其他：除上述分类之外的任何影响文档质量的问题。

关于详细的文档规范，请参考 香山文档贡献指南。

4. 提交 Issue 报告问题

在发现问题后，您即可在对应的文档仓库提交 Issue 来详细报告您所发现的文档问题。

  • 提交 Issue 时，请选择 “Document Bug Report” 类型，并按照 Issue 模板的提示提供详细信息。
  • 提交后，请等待社区审核者的回复。审核者将对您提交的问题进行评估和确认。

如果您发现的问题较为简单，您也可以直接提交 Pull Request 进行修复。要求见下。

5. 创建 Pull Request 修复问题

当您的问题被审核者确认并回复后，您可以根据审核者的建议，进行修改并提交 Pull Request:

提交 PR 时，请遵守以下注意事项：

  • PR 标题格式：fix(part/chapter): fix something
  • PR 描述需用英文，详细说明修改内容
  • 若修复特定 Issue，请附上 Fix #id

示例：

fix(memblock/MMU): fix wrong description of need_gpa

The previous document said that xxx, but actually xxxx.

Fix #23.

由于英文文档是通过 Weblate 平台翻译的，通常需要先在 Weblate 上修复，再同步到 Github。如果您不熟悉 Weblate 相关操作，建议您直接提交 Issue，由工作人员进行修复。

🏆 活动分数计算方式

  • 每个有效 Issue：1~3 分（根据重要程度、提报质量等综合评定）
    • 贡献者首个 Issue 有机会获得 Good First Issue 和 2 倍的分数加成
  • 每个合并的 PR：3~5 分（根据重要程度、贡献质量等综合确定）
    • 贡献者首个 PR 将获得 2 倍的分数加成
  • 个人总分 = 有效 Issue 分数 +  PR 分数  

🎁 丰厚奖励等你来拿！

香山社区为本次活动设置了丰厚的奖励，以感谢各位参与者的贡献。所有奖励将根据您的积分排名和贡献质量进行评选。

  • 最佳贡献奖（10 名）：罗技 Lift 人体工学鼠标 + 毛德操老师《RISC-V CPU 芯片设计：香山源代码剖析》书籍 + 香山环保袋 + 100 香山社区积分。
  • 优秀问题奖（15 名）：50 香山社区积分 + 户外便携野营音乐节水陆两用充气床 + 香山冰箱贴。
  • 积极参与奖（30 名）：10 香山社区积分 + 手持头部按摩仪 + 香山贴纸。
  • 特别奖励：PR 被合并到主干分支，额外获得 5 香山社区积分！

香山社区积分用途：香山培训兑换、礼品兑换、贡献排行榜排名。

🤝 社区支持

在活动过程中遇到任何问题，欢迎随时在 GitHub Issue 中提问，或关注香山社区官方渠道获取最新动态和支持信息。

  • 香山技术讨论 QQ 群：879550595

期待你的加入，和我们一起守护香山文档，共建更美好的开源社区！