2024 TiDB 文档挑战赛|为什么文档如此重要,如何让它变得更好?

文档是开源软件项目的关键组成部分。清晰、准确、易于理解的文档可以让用户轻松上手使用产品,并在产品使用的过程中通过文档自助解决遇到的大多数问题。

当需要评估某一技术产品或组织时,许多人通常会先看看他们的产品文档做得如何。如果他们有高质量的文档或其他入门资源,就会增加对其产品质量的信心。文档通常也是一个公司组织文化的体现:是否注重细节,该组织在社区中的支持力度如何,该组织的创新性如何等。

在过去,开源软件的主要用户是开发人员。如今,越来越多不同角色的人员也都成为了开源软件的关键用户,例如商业分析师、数据科学家等非专业开发人员。因此,拥有一套好的文档比以往任何时候都更为重要

TiDB 社区贡献的历史

从 TiDB 项目创建至今,TiDB 源码和 TiDB 文档源文件一直坚持开源的宗旨,可供所有用户随时查看源码、提供建议或提交修改。我们特别欢迎社区贡献者们参与到产品和产品文档的优化中(目前 TiDB 文档贡献者的数量已超过 800 人并在不断增长)。TiDB 的文档网站也非常受用户欢迎,在过去的 12 个月里,有超过 30 万用户访问了文档页面。

为了给大家提供高质量的文档,我们持续投入了大量的时间和资源到文档的质量和文档体验提升中,但同时我们也清晰地意识到没有完美的文档,没有人比我们的社区用户更适合帮助我们提升改进。我们十分需要从用户视角进一步完善并优化现有文档,只有用户才能给出真实的产品和文档的使用反馈,才能更有效地提升文档质量和体验。因此,我们特别需要也非常希望能邀请各位 TiDB 社区用户为我们的文档提供宝贵意见并贡献文档改进。

2024 TiDB 文档挑战赛正式发布啦!

在这里,我们很高兴地宣布首届TiDB 文档挑战赛 (TiDB Docs Dash) 活动将于 2024 年 1 月 9 日至 12 日举行。通过此次活动,我们希望将 TiDB 社区成员聚集在一起,大家共同改进 TiDB 文档TiDB Cloud 文档,并从活动中感受协作的乐趣。

你可以通过以下任一形式,参与到此次活动中来:

  • “调试”文档:按照文档(例如,某个新功能的文档)中的步骤完成操作,测试该文档是否完整准确

  • 完善现有文档中的说明和示例

  • 改善文档的可读性

  • 指出文档中的拼写或语法错误并给出改进意见

  • 中英文档翻译(例如从中文翻译成英文)

以上只列出了一部分文档贡献类型。我们坚信,卓越的 TiDB 社区成员们一定能提供更加惊喜的建议!

TiDB 文档挑战赛将如何进行?

活动开始前

我们将会为大家创建一个可以领取任务的 GitHub issue 列表(每个 issue 都将与需要被调试、翻译或改进的文档相关)。

活动期间

社区成员可以通过提交 Pull Request (PR),解决 issue,或在 issue 上评论/提出建议来参与文档贡献。每当你为 GitHub issue 列表中的 issue 提交 PR 或者提出有用的解决建议时,你将获得相应的得分。

对每个 PR 或 issue 做出的贡献不同,获得的得分也不相同(与在 GitHub issue 上评论或提出建议相比,提 PR 解决问题可以获得更高的得分)。

除了 GitHub issue 列表中列出的问题以外,我们也欢迎你指出或解决任何其他文档问题,例如修正拼写错误或改善可读性,这些贡献同样也可以通过创建 PR 或创建 issue 而获得得分。

活动结束后

我们将计算各个参与者的得分,为所有参与者提供定制的电子徽章,为 PR 被合并的作者提供社区积分,并为排名前五的参与者提供精美的奖品。详细的计分计划规则、活动礼品及其他重要信息,敬请关注 TiDB 文档挑战赛活动介绍页面

写在最后

如果你对 TiDB 或 TiDB Cloud 文档的改进感兴趣,并且想要参加一次有意义的社区活动,就在 2024 年 1 月 9 日至 12 日加入到我们的 TiDB 文档挑战赛活动中吧!

我们还在 DiscordSlack 上创建了 #2024-tidb-docs-dash 频道。欢迎加入这些频道,并关注活动公告。期待你发布任何活动相关的问题和建议~

同时,我们鼓励大家分享自己在使用 TiDB 文档时的真实体验,你可以随时在本帖的评论中或在我们的 Discord 或 Slack 频道上分享自己的想法!

非常期待我们此次活动中与大家合作! :raised_hands: :two_hearts:

2 个赞

:+1:

我们的文档确实需要专业一点的人好好编辑整理一下,看起来真的太乱了

? 具体说说建议

我们在遇到具体的问题时可以提建议和优化点,泛泛而谈无法让人信服。

说实在的,TiDB的文档对比大部分数据库产品都要好,这是大部分人都认可的观点。当然,它还有很多待优化的地方,这也是官方在举办这些活动的意义所在。大家集思广益,让社区的用户有更好的文档阅读体验。

文档确实很重要,很多时候我们都是哪些官方文档去当做操作手册,很多疑问也是以官方文档为准,很多学习也是跟着官方文档学习。

我自己翻译过MYSQL5.7和8的官方手册,两者对比起来差距还是很大的,文档的编辑也是一门很有技术的活。

至少tidb的文档是非常非常优秀的学习资料