Makedown 基本语法及文档写作草案

一：文档结构

Makedown 整体文档由上到下结构建议遵循如下写作模式。

3.1 标题

标题必须有，标题尽可能概况全文的目的，同时能让读者一目了然，迅速捕捉文档重点。切忌有模糊不清的概念，切忌有不太专业的说法，类似如下欠妥的标题尽量避免。

• mbedtls 示例
• 关于 mbedtls 使用的心得

mbedtls 示例标题太大，没有侧重点，读者读完仍不清楚这是介绍 mbedtls 原理还是 mbedtls 的上层应用示例还是其他的相关内容。
关于 mbedtls 使用的心得 标题偏随意，关于和的心得的用法偏业余。

3.2 关键词

关键词必须有，一来便于搜索引擎能准确定位文档，二来也便于读者能快速了解文档整体脉络。
关键词紧跟标题下一行，建议设置为 3-5 个。

3.3 文档内容结构

文档内容的部署尽可能组织有序，让读者能够快速跟随你的脚步，深层次理解整个文档。下面的内容组织可供笔者参考一二。

3.3.1 [可选] 目录

如果文档内容篇幅偏多，建议设置一个目录，具体设置可参考 Makedown 锚的语法，这样便于读者快速跳到自己感兴趣的章节。

3.3.2 相关知识介绍

相关知识介绍必须有，用来介绍该文档中一些较为专业或较为重要的知识，通常可能涉及标题中关键字眼，或文档关键技术。旨在让小白读者能够对该文重点部分或专业的地方有较为宏观的认知；让有相关知识涉猎的工程师能够加深印象并能触发共鸣。
可能这些相关知识对一些工程师来说是较为共识的，我们仍然建议加上相关知识介绍。比如：

文档标题为

ESP32 应用实践：基于 ULP 的超低功耗浇花设备

则在相关知识介绍里应有 ULP 的相关介绍，让小白读者知道 ULP 协处理器是什么，让熟悉 ULP 的工程师知道本文的 ULP 协处理器和自己理解的 ULP 协处理器是不是类似，是不是有新的功能或其他属性。

3.3.3 摘要/行文目的

这部分必须有，用来整理概括文档的核心思想。通过阅读本文，读者能够获取到哪些相关知识以及原理，或完成哪些特定目的。

3.3.4 [建议] 流程图

为了完成这个目的，笔者通过何种方式来实现，用流程图来展示其实现过程较为直观明了。
尤其是一些示例性的 Demo，流程图可快速让读者明白整个工作流程。

流程图下面，通常加上一段描述性段落，用来说明流程图的过程。

3.3.5 [建议] 工作原理

一篇技术文档中，总是涉及到一些原理性的东西。比如 mbedtls 内存开销可能会涉及内存和 SSL 握手相关的原理，SSL 握手哪一步会需要内存开销，以及 SSL 握手完分配的内存是否回收等。

3.3.6 开发环境搭建

如果文档以 Demo 为导向，需一步步介绍开发环境搭建过程。包括以下方面：

• 用到的所有硬件及其获取方式
• 你的开发系统，以及系统需要安装哪些软件及其步骤
• 整套代码获取，包括 IDF 和 Demo 对应的 SDK 获取方式
• 编译器获取
• 其他操作，如云端环境搭建等

3.3.7 示例步骤

示例中是否要修改一些代码，是否需要配置make menuconfig等参数，同时编译，烧写，运行过程等详细步骤需一步步按条列出来。如可用 a) b) c) … f) 或 1) 2) 3) … 6) 等方式列出来。

3.3.8 结果展示

结果的展示必须和预期目的相同。同时尽量直观些，可采用截图等方式，同时可附上一些说明。

3.3.9 核心代码说明

如果文档涉及到代码，则需要介绍一部分核心代码说明，每个核心代码都可加上一段简单说明。这部分代码通常是用来描述程序的关键步骤或关键技术等。

3.3.9 [可选] 测试部分

如果文档涉及到一些测试数据，尽量对测试部分做一个小结。采用表格或图形等其他方式来描述测试结果以及对应的测试环境。同时附上一些说明。

3.3.10 [可选] 本文注意事项

如果文档涉及到一些易错的操作，比如一些环境的搭建容易失败等问题需附加说明。

3.3.11 常见错误处理

常见的错误情况举例，一条条列出来。比如eth2wifi demo中为什么设备和手机都有 ip 却 ping 不通，那么可能是手机防火墙设置等问题。诸如此类，尽量排除可能出现的错误。

二：文档写作格式细节要求

• 同一个名词，全文尽量采用统一的称呼方式
• 大小写注意，采用通用的方式，如 WiFi,勿写成 Wifi，WIFI，Wi-Fi，wifi 等写法
• 全文采用中文标点，勿出现.或,等英文标点
• 英文单词前后需空一个英文的空格(占一字节)，如果前后遇到中文标点，则无需空一个字符
• 文档需按照段落有序组织，如 1.1 1.2这样自由组织，不要让读者看上去像是一坨的感觉
• 尽可能使用专业的词汇
• 文档如引用别人的文档，需找到最官方的那个文档，如引用wireshark 抓 80211 层报文,尽量从 wireshark 官方的链接引用
• 每段落结束后或每个标题结束后，需空一行

三：Makedown 基本语法

Makedown 建议采用如下七种方式，其他复杂的图形和公式或流程图建议采用截图方式。

3.1 每小结标题采用 # 方式

# 一级标题## 二级标题### 三级标题#### 四级标题##### 五级标题###### 六级标题

3.2 列表

列表格式也很常用，在 Markdown 中，你只需要在文字前面加上 - 就可以了，例如：

- 文本1- 文本2- 文本3

如果你希望有序列表，在文字前面加上 1. 2. 3. 就可以了，例如：

1. 文本12. 文本23. 文本3

3.3 链接和图片

在 Markdown 中，插入链接不需要其他按钮，你只需要使用[显示文本](链接地址) 这样的语法即可，例如：

[ESP官网](https://www.espressif.com)

在 Markdown 中，插入图片不需要其他按钮，你只需要使用 ![](图片链接地址)这样的语法即可，例如：

![插入图片](http://upload-images.jianshu.io/upload_images/259-0ad0d0bfc1c608b6.jpg?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

3.4 引用

在我们写作的时候经常需要引用他人的文字，这个时候引用这个格式就很有必要了，在 Markdown 中，你只需要在你希望引用的文字前面加上 > 就好了，例如：

> 一盏灯， 一片昏黄； 一简书， 一杯淡茶。 守着那一份淡定， 品读属于自己的寂寞。 保持淡定， 才能欣赏到最美丽的风景！ 保持淡定， 人生从此不再寂寞。

注：> 和文本之间要保留一个字符的空格。

3.5 粗体和斜体

Markdown 的粗体和斜体也非常简单，用两个 * 包含一段文本就是粗体的语法，用一个 * 包含一段文本就是斜体的语法。

**我是粗体***我是斜体*

3.6 代码引用

需要引用代码时，如果引用的语句只有一段，不分行，可以用 ` 将语句包起来。

`我是代码行`

如果引用的语句为多行，在引用的前后使用三个 ` 将这段引用或代码包含进来。

```

// 代码段1
// 代码段2
// 代码段3

```

3.7 表格

表格例子如下：

| Tables        | Are           | Cool  || -------- ---- |:-------------:| -----:|| col 3 is      | right-aligned | $1600 || col 2 is      | centered      |   $12 || zebra stripes | are neat      |    $1 |

这种语法生成的表格如下：

Tables Are Cool col 3 is right-aligned $1600 col 2 is centered $12 zebra stripes are neat $1