Markdown 写作规范

Markdown 写作规范

这门内容的目标不是“把 Markdown 所有语法都背下来”，而是帮你建立一套适合课程作业、开源项目和团队协作的文档习惯。你会发现：写得清楚的人，往往也比别人更容易获得合作机会。

本章目标

• 建立清晰、可扫描的文档结构
• 掌握课程作业和项目 README 的最小可用写法
• 减少“写了很多，但别人看不懂”的情况

为什么写作能力很重要

很多学生把文档当成“写完代码后的补丁”，但实际上文档常常决定别人怎么评价你的项目。一个结构清晰、重点突出的 README，比一段没有注释的复杂代码更容易获得认可。

课程作业里，老师不一定有时间仔细看每一行实现，但通常会快速扫一遍：

• 这个项目解决了什么问题
• 我怎么运行它
• 我该看哪些文件

如果你能在三分钟内让读者建立正确预期，你的项目就已经赢了一半。

标题与层级规范

Markdown 的标题不是“越大越重要”，而是代表信息层级。建议你先建立这套最小层级：

• #：页面或文档标题
• ##：一级章节
• ###：二级小节
• ####：补充说明或边界条件

常见问题是：一篇文档里 # 用得太多，导致读者看不出主次。更实用的写法是：整个文档只保留一个 #，其余都用 ## 和 ### 组织。

列表与说明结构

学生项目里最常见的说明结构其实是列表，而不是长段落。最小可用的原则是：

• 每项只说一件事
• 每项长度尽量接近
• 列表项不超过 7 个，否则拆成小节

如果你发现自己在写很长的无序列表，通常意味着应该加小节标题，而不是继续堆 bullet。

代码块与命令展示

课程作业和技术文档里，命令和代码是最容易被误写的地方。建议你这样做：

• 标明语言类型，方便高亮
• 只保留必要命令，不要截图整段终端
• 复杂命令先写一句话说明，再贴代码

一个最小示例：

# 安装依赖
npm install
# 启动项目
npm run dev

不要默认认为所有人都和你用同一套环境，一句“在项目根目录执行”就能减少很多误解。

链接与引用规范

写 README 或课程文档时，链接不是“能跳就行”，而是要让读者知道点击后能得到什么。建议格式是：

• 内部路径说明当前页相对位置
• 外部链接说明资源类型，例如“官方文档”“参考实现”“课程要求”

不要只写“参考这里”，而要写“参考这里了解 API 设计约束”。信息越具体，读者越愿意点击。

表格与结构化信息

课程实验、接口说明、版本对比都很适合用表格表达。Markdown 表格的最小价值是“减少读者来回翻找”。建议这样用：

• 表头尽量短，但能独立理解
• 同一列保持同类信息
• 超过五行时，优先考虑是否还能再分小节

一个最小示例：

命令	用途	常用场景
git status	查看当前状态	提交前检查
git log --oneline -5	查看最近提交	确认提交历史

提示、注意与警告框

文档里最值得复用的结构不是强调色，而是提示框。建议你至少建立三种框：

• 提示：更快完成任务的捷径
• 注意：容易踩坑的边界条件
• 警告：可能导致数据丢失或协作异常的操作

写作时不要滥用，只在确实会影响读者下一步行为时才使用。

学生文档的最小检查清单

提交课程作业或 README 前，按这个顺序检查通常最快：

1. 先看标题是否准确概括内容
2. 再看章节顺序是否从背景到操作再到说明
3. 检查命令是否都经过实际运行验证
4. 检查链接是否仍可访问
5. 检查是否有“我以为很明显”但其实没写清的假设

能做到这五步，大多数文档问题会在提交前被发现。

进阶补充：文档可维护性

很多学生文档一开始能看懂，但两周后自己都看不懂。要减少这种情况，可以这样做：

• 版本或时间敏感信息单独放在一个章节
• 不要在一段里混合“背景说明”和“操作步骤”
• 同一个概念在全篇使用统一说法，不要一会叫“组件”，一会叫“模块”

可维护性不是“写得更漂亮”，而是“下次修改时，你能更快找到哪里该改”。

进阶补充：从草稿到定稿

如果你容易写出冗长文档，可以试试这个流程：

1. 先列提纲，只写标题
2. 每个标题下只写 3 条关键信息
3. 再回头把每条信息扩成 1-3 句话
4. 最后统一删掉重复和不必要的形容词

这个流程能帮你从“想到哪写到哪”变成“先结构，再填充”。

进阶补充：README 的最小结构

课程项目、作品集、开源项目都适合这套最小 README 结构：

• 项目名称与一句话介绍
• 运行方式
• 核心功能或目录说明
• 依赖与版本要求
• 使用示例或截图
• 学习收获与可改进点

如果你要投简历或课程展示，这套结构能让老师在 30 秒内看懂你的项目价值。

进阶补充：协作文档的边界

多人协作时，文档最容易出问题的不是“写得太少”，而是“版本不统一”。最小建议是：

• README 只放当前版本最准确信息
• 过期说明移到历史文档或 changelog
• 不要把三种不同版本的配置说明混在同一份文档里

降低读者的认知负担，比展示你知道更多细节更重要。

即学即练

<InteractiveQuiz title=“Markdown 小测” questions={[ { question: ‘Markdown 文档里通常建议保留几个顶级标题？’, options: [‘越多越好’, ‘0 个’, ‘1 个’, ‘和段落数一样多’], correctValue: ‘1 个’, explanation: ‘通常建议整个文档只保留一个顶级标题，其余用二级、三级标题组织内容。’, }, { question: ‘Markdown 表格最适合表达哪类信息？’, options: [‘纯故事叙述’, ‘结构化对比和字段说明’, ‘长段抒情’, ‘代码实现’], correctValue: ‘结构化对比和字段说明’, explanation: ‘表格适合让读者快速对照字段、命令或版本差异。’, }, { question: ‘README 最小结构里最优先写清楚的是？’, options: [‘作者心情’, ‘运行方式和项目用途’, ‘无用历史信息’, ‘仅放截图’], correctValue: ‘运行方式和项目用途’, explanation: ‘能快速运行并理解用途，是 README 的核心价值。’, }, ]} />