README 里的表格应该帮助访问者更快回答一个具体问题:我该安装哪个包?哪个功能可用?哪个环境通过了?如果把表格当作通用页面布局,或者塞进手机屏幕根本放不下的大段文字,它就会变成负担。
让每一列只负责一件事
表头要短而明确。Package、Runtime 和 Status 比 Information 1、Information 2、Information 3 更有信息量。需要多句说明的内容,应该放在表格外面。
| Package | Runtime | Status |
| :--- | :---: | :---: |
| `core` | Node 22 | Stable |
| `cli` | Node 22 | Beta |
第一列通常左对齐,因为名称本来就是按文本扫读的。紧凑的运行时和状态字段可以居中。数字型基准结果通常应该右对齐。
使用有意义的链接文本
不要把很长的原始 URL 直接塞进单元格。像 [API reference](./docs/api.md) 这样的链接既能缩短列宽,也能告诉屏幕阅读器目标内容是什么。如果表格里反复出现“click here”之类的链接,离开上下文后它们就失去意义了。
徽章本质上是图片,过多会增加视觉噪音。只在少量持续变化的信号上使用它们,不要把每一行都装饰一遍。最好在徽章链接或周围文字里提供有用的替代文本。
优化源码审阅
Pull Request 审阅者会同时看渲染结果和 diff。尽量做到一行一条记录。如果只是普通值变化,不要手工补齐几百个空格,否则每次改动都会重写整张表。对于自动生成的兼容性矩阵,最好提交生成脚本或源文件,方便审阅者追溯数据来源。
检查窄屏
GitHub 也许允许宽表格横向滚动,但用户很容易丢失行上下文。把最重要的识别列放在最前面,减少列数,并把不相关的维度拆成多张表。如果某一行比其他行长很多,它大概率更适合放在单独的小节里。
保持声明最新
功能矩阵和支持表会很快过期。把它们纳入和代码相同的审查流程。某次发布如果改变了兼容性,应该在同一个 Pull Request 里更新 README,而不是等后面再补。
先在 Markdown 表格生成器 中创建并对齐源码,再在分支或 PR 中确认最终渲染效果,然后合并。