【 TiDBer 唠嗑茶话会 38 】关于文档的爱恨情仇,统统可以在这里倾诉~

前言

TiDB 社区 中, TiDBer 不断地给我们 文档优化 出谋献策,自 文档优化 板块上线后,我们前前后后收集了 70 个关于文档错误、文档需求,其中有 68 个建议已经接受并完整实现,剩下的 2 个还有优化中…

随着产品的迭代,文档的重要性也越来越明显,完整、详尽、好理解的文档,通常是 TiDBer 处理 TiDB 问题的一大利器。

我们深知 现有文档 的不足,需要优化、迭代的内容实在太多了,而文档新增的 优先性、详细程度等 这些都需要跟进 TiDBer 的需求来做一个合理的规划。所以,我们希望通过本次调研, TiDBer 能够给一些 case by case 的文档建议,与文档团队共同打磨文档,让文档也能帮助更多 TiDBer 去处理和解决 日常工作中遇到的技术难题

本期话题:

在评论区留下 case by case 按照事实举例的文档优化需求。

如果你遇到以下问题:

  • 文档错误
  • 部分文档看不懂
  • 缺少某部分文档说明

吐槽按照以下流程提交:

文档错误

如果你遇到 文档错误 ,请按照下方模板反馈,可以让我们更快定位到问题,以便于第一时间做出修改:

  • 问题分类:更新不及时、描述错误、代码错误、参数错误、链接错误、错别字
  • 出现的页面:链接+截图
  • 出现的错误:

文档不清晰或不完整

如果你对部分文档描述不理解,请按照下方模板提交,以便于我们更清楚你遇到的困惑:

  • 问题分类:内容太简略、描述不清有歧义、步骤不完整
  • 出现的页面:链接+截图
  • 出现的问题:

文档新增需求

如果这是个 文档新增需求 ,请按照下方模板提交,以便于我们更快了解到你的需求,进行优化:

  • 需求类型:新增文档
  • 需求背景:比如缺少哪部分文档,对使用有什么影响
  • 期望增加哪些组件或者功能的文档,加到现有文档的哪个位置

反馈奖励:

  • 抽 1 名反馈问题的小伙伴奖励 TiDB 新版挎包,抽 1名 反馈问题小伙伴奖励 TiDB cloud 限量款马克杯
  • 按照模板参与反馈文档问题奖励 100积分、100经验值
  • 一一兑现需求(前提:建议可行)

TiDB 新版挎包

TiDB cloud 限量款马克杯

本期唠嗑茶话会未按照模板参与不做奖励~

TiDB文档已经很完美了,但是可以更完美,PM大大,你懂我意思不:wink:

抛个砖

2赞

之前提的文档issue还没合并:sweat_smile:

文档这块,TiDB一个组件叫Tidb,我觉得这个组件名称不好,数据库名称叫tidb,组件也叫tidb,这个很容易混肴。
可以考虑以下几个名字:
Ticp cp是计算的英文简写
Tijs js是计算的中文简写
Tisql 别人一看这个名字就知道这个组件是处理sql的。
Tiql 同tisql(4个字母主要是tikv保持一致)

大家可以帮忙想想有没有其他更合适的名字。

你说的组件是 TiDB Server 吧?
https://docs.pingcap.com/zh/tidb/stable/tidb-architecture

是的,TiDB Server, 这个名字也不好,Ti Database server (钛数据库服务器)

这么优秀的国产数据库,走出国门,走向世界,名字简单明了,不要有不好理解的地方。

:rofl:这位同学是不是对 TiDB Server 有误解~ 这是一个服务组件,不是服务器

望文生义了

嘿嘿,可以归到问题分类里的 描述不清有歧义 了:wink:

慢查询日志,字段含义说明中少了对很多字段的解释说明,例如Commit_backoff_time、Backoff_types、Wait_prewrite_binlog_time、Resolve_lock_time、Rocksdb_delete_skipped_count、Rocksdb_key_skipped_count、Rocksdb_block_cache_hit_count等等

https://docs.pingcap.com/zh/tidb/stable/identify-slow-queries

1赞

能否标注下 tidb 5.x 不在支持 binlog 了,要大写的,或者醒目的,,

这有个要升级到6.1.1 的案例,就是5.x 不装 ticdc, 但是装了binlog 的组件,问为啥不能升级… :joy:

文档里有写参数说明不够详细,很简单的展示了一下。具体参数详细说明并没有。
取值范围,默认值,是否重启生效等等,可以更完善。

前两天在离线安装V6.1.1的时候有遇到了,我是按照之前V5.4的安装步骤来的。
原因是V6.0后,2个离线包的内容发生了比较大的变化,很多组件安装包都挪到toolkit里面去了。导致安装的时候如果只解压server包会就会出血找不到组件的问题。但是日志提示并不明显。

建议
在上面截图中的位置,加上一步:解压 toolkit 包并合并镜像到server目录
这一步是必须的,当前描述『若需将 server 和 toolkit 两个离线镜像合并,执行以下命令合并离线组件到 server 目录下。』可能会让人误认为是可选的,或者不清楚什么时候需要合并。:grinning:

描述半天,不知道我有没有表达清楚:grinning:

1赞

似乎不太适合0基础的,感觉更习惯Oracle文档

tidb 文档已经很好了 , 有的数据库文件跟看天书一样 满篇错误

1赞

tidb的文档可以的,一起努力找找问题,补充补充细节完美,对比某云厂商的文档连最基本的语法都不完善。。。