A README table should help a visitor answer a specific question faster: Which package should I install? Which feature is supported? Which environment passed? Tables become counterproductive when they are used as a general page layout or contain paragraphs that cannot fit on a small screen.
Give every column one job
Use short, concrete headers. Package, Runtime, and Status communicate more than Information 1, Information 2, and Information 3. Keep descriptions outside the table when they require multiple sentences.
| Package | Runtime | Status |
| :--- | :---: | :---: |
| `core` | Node 22 | Stable |
| `cli` | Node 22 | Beta |The first column is left-aligned because names are scanned as text. Compact runtime and status fields are centered. Numeric benchmark results would normally be right-aligned.
Prefer links with meaningful labels
Avoid pasting long raw URLs into cells. A link such as [API reference](./docs/api.md) keeps the column compact and tells screen-reader users what the destination contains. If a table contains repeated “click here” links, the links lose meaning outside the surrounding visual context.
Badges are images and can increase visual noise. Use them for a small number of continuously updated signals, not as decoration in every row. Provide useful alternative text in the badge URL or surrounding link.
Optimize for source review
Pull request reviewers read both the rendered table and its diff. Keep one record per line. Avoid manually aligning hundreds of spaces if routine value changes will rewrite every row. For a generated compatibility matrix, commit the generating script or source file so reviewers can trace where values came from.
Check narrow screens
GitHub may allow a wide table to scroll horizontally, but users can lose the row context. Put the most important identifying column first, limit column count, and split unrelated dimensions into separate tables. If one row contains much more text than the others, it probably belongs in a dedicated section.
Keep claims current
Feature matrices and support tables age quickly. Add the table to the same review process as the code it describes. When a release changes compatibility, update the README in the same pull request rather than relying on a later documentation pass.
Create and align the source in the Markdown table generator, then verify the final rendering in a branch or pull request before merging.