> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 第三天| 实战与最佳实践

> 文档结构设计、协作工具使用和常见问题解决

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

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="book" size={26} color="#059669" /> 学习内容 (20 mins)</span>

<AccordionGroup>
  <Accordion title="1. 文档结构设计 (10 mins)" icon="sitemap">
    **好的文档结构**

    一个结构清晰的文档应该包含：

    * **标题**：明确文档主题
    * **目录**：快速导航（可选）
    * **概述**：文档目的和范围
    * **正文**：主要内容，分章节
    * **附录**：参考资料、常见问题等

    **标准结构模板**：

    ```markdown theme={null}
    # 文档标题

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

    ## 概述

    本文档说明...

    ## 快速开始

    ### 安装
    ### 配置

    ## 详细说明

    ## 常见问题

    ## 参考资源
    ```

    **设计原则**：

    * **层次清晰**：标题层级不超过 4 级
    * **逻辑顺序**：从概述到细节
    * **易于查找**：重要信息放在前面
  </Accordion>

  <Accordion title="2. 协作工具使用 (10 mins)" icon="users">
    **常用平台**

    | 平台     | 特点              | 适用场景      |
    | ------ | --------------- | --------- |
    | GitHub | 代码托管、Issue、Wiki | 技术文档、项目文档 |
    | Notion | 强大的数据库功能        | 知识库、团队协作  |
    | 语雀     | 中文友好、模板丰富       | 产品文档、内部文档 |
    | 飞书文档   | 集成办公套件          | 会议记录、项目报告 |

    **GitHub 使用技巧**：

    * 支持直接拖拽图片
    * Issue 和 PR 描述支持 Markdown
    * Wiki 页面用 Markdown 编写
    * 可以预览 `.md` 文件

    **Notion 使用技巧**：

    * 输入 `/` 快速插入 Markdown 元素
    * 支持数据库视图（表格、看板等）
    * 可以嵌入代码块、公式等
  </Accordion>
</AccordionGroup>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="code" size={26} color="#059669" /> 实践任务 (80 mins)</span>

<Steps>
  <Step title="任务 1: 设计完整的项目文档">
    创建一个完整的项目文档，包含所有必要部分。

    **文档要求**：

    1. **标题和概述**
       ```markdown theme={null}
       # 项目名称

       > **项目简介**：简要说明项目的目的和价值
       ```

    2. **目录（可选）**
       ```markdown theme={null}
       ## 目录
       - [快速开始](#快速开始)
       - [功能特性](#功能特性)
       - [使用说明](#使用说明)
       - [常见问题](#常见问题)
       ```

    3. **功能特性（用列表）**
       ```markdown theme={null}
       ## 功能特性

       - ✅ 功能 1
       - ✅ 功能 2
       - 🚧 功能 3（开发中）
       ```

    4. **使用说明（用代码块）**

       ````markdown theme={null}
       ## 使用说明

       ### 安装

       ```bash
       npm install
       ````

       ### 运行

       ```bash theme={null}
       npm start
       ```

       ```
       ```

    5. **进度表格**
       ```markdown theme={null}
       ## 项目进度

       | 模块 | 状态 | 完成度 |
       |:-----|:----:|------:|
       | 前端 | 进行中 | 60% |
       | 后端 | 已完成 | 100% |
       ```

    6. **常见问题（用引用块）**
       ```markdown theme={null}
       ## 常见问题

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

  <Step title="任务 2: 在协作平台上发布">
    选择一个协作平台，发布你的文档。

    **GitHub 方式**：

    1. 创建仓库或使用现有仓库
    2. 创建 `.md` 文件
    3. 提交并推送
    4. 在网页上查看效果

    **Notion 方式**：

    1. 创建新页面
    2. 直接输入 Markdown（会自动转换）
    3. 或使用 `/` 命令插入元素

    **语雀方式**：

    1. 创建知识库
    2. 新建文档
    3. 使用 Markdown 编辑器
    4. 可以插入丰富的组件

    **实践任务**：

    选择你常用的平台，发布你的项目文档。
  </Step>

  <Step title="任务 3: 编写会议记录">
    用 Markdown 写一份会议记录。

    **会议记录模板**：

    ```markdown theme={null}
    # 周会记录 - 2024-01-31

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

    ## 会议议题

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

    ### 2. 本周任务

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

    ## 会议决议

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

    ## 行动项

    - [ ] 张三：更新项目计划
    - [ ] 李四：准备开发环境
    - [ ] 王五：完成 UI 设计稿
    ```

    **实践任务**：

    写一份真实的会议记录（可以是本周的会议）。
  </Step>
</Steps>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="lightbulb" size={26} color="#059669" /> 最佳实践 (20 mins)</span>

<CardGroup cols={2}>
  <Card title="写作规范" icon="pen">
    **标题规范**：

    * 一级标题用于文档标题
    * 二级标题用于主要章节
    * 不要跳级（如一级直接到三级）

    **列表规范**：

    * 统一使用 `-` 表示无序列表
    * 列表项前统一使用 2 个空格
    * 嵌套列表使用 4 个空格缩进

    **代码规范**：

    * 行内代码用反引号包裹
    * 代码块指定语言类型
    * 长代码块添加说明注释
  </Card>

  <Card title="协作规范" icon="users">
    **版本控制**：

    * 使用 Git 管理文档版本
    * 提交信息清晰（如：更新项目进度）
    * 定期备份重要文档

    **命名规范**：

    * 文件名使用小写和连字符：`project-readme.md`
    * 避免使用中文文件名（某些系统不支持）
    * 重要文档使用 `README.md`

    **审查流程**：

    * 重要文档提交 PR 审查
    * 使用 Issue 跟踪文档问题
    * 定期更新过时内容
  </Card>
</CardGroup>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="code" size={26} color="#059669" /> 今日作业 (20 mins)</span>

<CardGroup cols={1}>
  <Card title="作业：完成一个完整的项目文档" icon="file">
    **要求**：

    1. **选择一个真实项目**（可以是工作项目或个人项目）

    2. **文档必须包含**：
       * 项目概述（用引用块）
       * 目录（可选）
       * 功能特性（用列表）
       * 使用说明（用代码块）
       * 项目进度（用表格）
       * 常见问题（用引用块）
       * 相关链接

    3. **在协作平台上发布**：
       * GitHub、Notion、语雀等任选一个
       * 确保格式正确、美观

    4. **提交方式**：
       * 提供文档链接
       * 或导出 PDF 提交

    **评分标准**：

    * ✅ 结构完整（30 分）
    * ✅ 语法正确（30 分）
    * ✅ 内容实用（20 分）
    * ✅ 格式美观（20 分）
  </Card>
</CardGroup>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="file" size={26} color="#059669" /> 今日产出物</span>

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

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="github" size={26} color="#059669" /> 参考资源</span>

<CardGroup cols={2}>
  <Card title="查看参考示例" icon="code" href="https://github.com/akriamail/insightful-ops/tree/main/docs/mintlify/scripts/training/markdown-training/day-03">
    在 GitHub 查看完整示例

    <br />

    <small>包含项目文档和会议记录模板</small>
  </Card>

  <Card title="Markdown 最佳实践" icon="book" href="https://www.markdownguide.org/basic-syntax/">
    官方最佳实践指南

    <br />

    <small>学习更多技巧</small>
  </Card>
</CardGroup>

***

## 常见问题解决

<AccordionGroup>
  <Accordion title="Q: 表格在 GitHub 上显示不正常？">
    A: 检查：

    * 分隔线是否正确（第二行）
    * 列数是否一致
    * 对齐符号是否正确
  </Accordion>

  <Accordion title="Q: 图片上传后显示不出来？">
    A: 检查：

    * URL 是否正确
    * 图片是否公开访问
    * 相对路径是否正确（GitHub 需要相对仓库根目录）
  </Accordion>

  <Accordion title="Q: 代码块没有语法高亮？">
    A: 确保：

    * 使用了三个反引号
    * 指定了正确的语言标识
    * 编辑器支持语法高亮
  </Accordion>

  <Accordion title="Q: 不同平台显示效果不一样？">
    A: 这是正常的。不同平台对 Markdown 的扩展不同：

    * GitHub 支持更多扩展语法
    * Notion 有自己的组件系统
    * 建议在目标平台测试效果
  </Accordion>
</AccordionGroup>

***

## 🎓 培训总结

恭喜你完成了 3 天的 Markdown 培训！

**你已经掌握**：

* ✅ 基础语法（标题、段落、列表、强调、代码）
* ✅ 进阶语法（表格、链接、图片、引用、任务列表）
* ✅ 实战应用（文档设计、协作工具、最佳实践）

**下一步**：

* 在实际工作中多使用 Markdown
* 关注不同平台的扩展语法
* 建立团队的文档规范
* 持续学习和改进

***

<CardGroup cols={2}>
  <Card title="上一天: 进阶语法" href="/training/markdown-training/day-02">
    Day 2 | 表格、链接与图片
  </Card>

  <Card title="回到概览" href="/training/markdown-training/overview">
    查看完整培训计划
  </Card>
</CardGroup>