Skip to main content
今日目标：将前两天的知识应用到实际工作中，学会设计文档结构、使用协作工具，并掌握 Markdown 的最佳实践。

​
学习内容 (20 mins)

好的文档结构一个结构清晰的文档应该包含：
  • 标题：明确文档主题
  • 目录：快速导航（可选）
  • 概述：文档目的和范围
  • 正文：主要内容，分章节
  • 附录：参考资料、常见问题等
标准结构模板：
设计原则：
  • 层次清晰：标题层级不超过 4 级
  • 逻辑顺序：从概述到细节
  • 易于查找：重要信息放在前面
常用平台GitHub 使用技巧：
  • 支持直接拖拽图片
  • Issue 和 PR 描述支持 Markdown
  • Wiki 页面用 Markdown 编写
  • 可以预览 .md 文件
Notion 使用技巧：
  • 输入 / 快速插入 Markdown 元素
  • 支持数据库视图（表格、看板等）
  • 可以嵌入代码块、公式等

​
实践任务 (80 mins)

1

任务 1: 设计完整的项目文档

创建一个完整的项目文档，包含所有必要部分。文档要求：
  1. 标题和概述
  2. 目录（可选）
  3. 功能特性（用列表）
  4. 使用说明（用代码块）

    ​
    运行

  5. 进度表格
  6. 常见问题（用引用块）
2

任务 2: 在协作平台上发布

选择一个协作平台，发布你的文档。GitHub 方式：
  1. 创建仓库或使用现有仓库
  2. 创建 .md 文件
  3. 提交并推送
  4. 在网页上查看效果
Notion 方式：
  1. 创建新页面
  2. 直接输入 Markdown（会自动转换）
  3. 或使用 / 命令插入元素
语雀方式：
  1. 创建知识库
  2. 新建文档
  3. 使用 Markdown 编辑器
  4. 可以插入丰富的组件
实践任务：选择你常用的平台，发布你的项目文档。
3

任务 3: 编写会议记录

用 Markdown 写一份会议记录。会议记录模板：
实践任务：写一份真实的会议记录（可以是本周的会议）。

​
最佳实践 (20 mins)

写作规范

标题规范：
  • 一级标题用于文档标题
  • 二级标题用于主要章节
  • 不要跳级（如一级直接到三级）
列表规范：
  • 统一使用 - 表示无序列表
  • 列表项前统一使用 2 个空格
  • 嵌套列表使用 4 个空格缩进
代码规范：
  • 行内代码用反引号包裹
  • 代码块指定语言类型
  • 长代码块添加说明注释

协作规范

版本控制：
  • 使用 Git 管理文档版本
  • 提交信息清晰（如：更新项目进度）
  • 定期备份重要文档
命名规范：
  • 文件名使用小写和连字符：project-readme.md
  • 避免使用中文文件名（某些系统不支持）
  • 重要文档使用 README.md
审查流程：
  • 重要文档提交 PR 审查
  • 使用 Issue 跟踪文档问题
  • 定期更新过时内容

​
今日作业 (20 mins)

作业：完成一个完整的项目文档

要求：
  1. 选择一个真实项目（可以是工作项目或个人项目）
  2. 文档必须包含：
    • 项目概述（用引用块）
    • 目录（可选）
    • 功能特性（用列表）
    • 使用说明（用代码块）
    • 项目进度（用表格）
    • 常见问题（用引用块）
    • 相关链接
  3. 在协作平台上发布：
    • GitHub、Notion、语雀等任选一个
    • 确保格式正确、美观
  4. 提交方式：
    • 提供文档链接
    • 或导出 PDF 提交
评分标准：
  • ✅ 结构完整（30 分）
  • ✅ 语法正确（30 分）
  • ✅ 内容实用（20 分）
  • ✅ 格式美观（20 分）

​
今日产出物

  • 完整的项目文档（发布在协作平台）
  • 会议记录模板
  • 掌握文档设计和协作工具使用

​
参考资源

查看参考示例

在 GitHub 查看完整示例

Markdown 最佳实践

官方最佳实践指南

​
常见问题解决

A: 检查：
  • 分隔线是否正确（第二行）
  • 列数是否一致
  • 对齐符号是否正确
A: 检查：
  • URL 是否正确
  • 图片是否公开访问
  • 相对路径是否正确（GitHub 需要相对仓库根目录）
A: 确保：
  • 使用了三个反引号
  • 指定了正确的语言标识
  • 编辑器支持语法高亮
A: 这是正常的。不同平台对 Markdown 的扩展不同：
  • GitHub 支持更多扩展语法
  • Notion 有自己的组件系统
  • 建议在目标平台测试效果

​
🎓 培训总结

恭喜你完成了 3 天的 Markdown 培训！ 你已经掌握：
  • ✅ 基础语法（标题、段落、列表、强调、代码）
  • ✅ 进阶语法（表格、链接、图片、引用、任务列表）
  • ✅ 实战应用（文档设计、协作工具、最佳实践）
下一步：
  • 在实际工作中多使用 Markdown
  • 关注不同平台的扩展语法
  • 建立团队的文档规范
  • 持续学习和改进

上一天: 进阶语法

Day 2 | 表格、链接与图片

回到概览

查看完整培训计划