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

​
学习内容 (20 mins)

好的文档结构一个结构清晰的文档应该包含：
  • 标题：明确文档主题
  • 目录：快速导航（可选）
  • 概述：文档目的和范围
  • 正文：主要内容，分章节
  • 附录：参考资料、常见问题等
标准结构模板：
# 文档标题

## 目录
- [概述](#概述)
- [快速开始](#快速开始)
- [详细说明](#详细说明)
- [常见问题](#常见问题)

## 概述

本文档说明...

## 快速开始

### 安装
### 配置

## 详细说明

## 常见问题

## 参考资源
设计原则：
  • 层次清晰：标题层级不超过 4 级
  • 逻辑顺序：从概述到细节
  • 易于查找：重要信息放在前面
常用平台
平台特点适用场景
GitHub代码托管、Issue、Wiki技术文档、项目文档
Notion强大的数据库功能知识库、团队协作
语雀中文友好、模板丰富产品文档、内部文档
飞书文档集成办公套件会议记录、项目报告
GitHub 使用技巧：
  • 支持直接拖拽图片
  • Issue 和 PR 描述支持 Markdown
  • Wiki 页面用 Markdown 编写
  • 可以预览 .md 文件
Notion 使用技巧：
  • 输入 / 快速插入 Markdown 元素
  • 支持数据库视图（表格、看板等）
  • 可以嵌入代码块、公式等

​
实践任务 (80 mins)

1

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

创建一个完整的项目文档，包含所有必要部分。文档要求：
  1. 标题和概述 
    # 项目名称

> **项目简介**：简要说明项目的目的和价值
  2. 目录（可选） 
    ## 目录
- [快速开始](#快速开始)
- [功能特性](#功能特性)
- [使用说明](#使用说明)
- [常见问题](#常见问题)
  3. 功能特性（用列表） 
    ## 功能特性

- ✅ 功能 1
- ✅ 功能 2
- 🚧 功能 3（开发中）
  4. 使用说明（用代码块） 
    ## 使用说明

### 安装

```bash
npm install

    ​
    运行

    npm start
  5. 进度表格 
    ## 项目进度

| 模块 | 状态 | 完成度 |
|:-----|:----:|------:|
| 前端 | 进行中 | 60% |
| 后端 | 已完成 | 100% |
  6. 常见问题（用引用块） 
    ## 常见问题

> **Q: 如何重置密码？**  
> A: 点击登录页面的"忘记密码"链接。
2

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

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

任务 3: 编写会议记录

用 Markdown 写一份会议记录。会议记录模板：
# 周会记录 - 2024-01-31

## 参会人员
- 张三（产品经理）
- 李四（开发）
- 王五（设计）

## 会议议题

### 1. 项目进度回顾
- [x] 完成需求分析
- [ ] UI 设计进行中

### 2. 本周任务

| 任务 | 负责人 | 截止时间 |
|:-----|:------:|:--------:|
| 完成设计 | 王五 | 2月5日 |
| 开始开发 | 李四 | 2月7日 |

## 会议决议

> **重要决定**：项目延期一周，新的上线时间为 2月15日。

## 行动项

- [ ] 张三：更新项目计划
- [ ] 李四：准备开发环境
- [ ] 王五：完成 UI 设计稿
实践任务：写一份真实的会议记录（可以是本周的会议）。

​
最佳实践 (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 | 表格、链接与图片

回到概览

查看完整培训计划