表格、提示框与提交前检查
你将学会什么
Section titled “你将学会什么”- 用表格表达字段、命令与版本对比
- 区分提示、注意、警告三种提示框的用法
- 提交文档前按五步检查清单过一遍
课程实验、接口说明、版本对比都很适合用表格表达。Markdown 表格的最小价值是「减少读者来回翻找」。建议这样用：
- 表头尽量短，但能独立理解
- 同一列保持同类信息，超过五行时再考虑分小节
比如把 git status 和 git log --oneline -5 放进一张表，读者一眼就能对照用途与使用场景。
文档里最值得复用的结构不是强调色，而是提示框。建议你至少建立三种框：
- 提示：更快完成任务的捷径
- 注意：容易踩坑的边界条件
- 警告：可能导致数据丢失或协作异常的操作
提交课程作业或 README 前，按这个顺序检查通常最快：
- 先看标题是否准确概括内容
- 再看章节顺序是否从背景到操作再到说明
- 检查命令是否都经过实际运行验证
- 检查链接是否仍可访问
- 检查是否有「我以为很明显」但其实没写清的假设
先自己回答，再看答案：
- 表格最适合承载哪类信息？
- 「警告」和「注意」的区别是什么？
- 检查清单里，哪一步最容易被人跳过？
参考答案
- 结构化对比和字段说明，如命令、版本、接口参数，让读者快速对照。
- 「注意」提示边界条件，「警告」指向可能导致数据丢失或协作异常的操作，风险更高。
- 第五步（检查没写清的假设），因为它需要把自己当成第一次读文档的人。
- 表格减少读者来回翻找，表头要能独立理解
- 提示/注意/警告各有边界，只在影响下一步行为时使用
- 提交前按「标题 → 结构 → 命令 → 链接 → 假设」五步检查