如何使用Markdown撰写技术文档

• 本文不涉及具体的 Markdown 语法教学

---

本文主要介绍在使用 Markdown 语法来进行技术文档写作时，如何选用合适的语法元素进行排版，使得文档具有清晰的逻辑、友好的可读性以及美观的形式。

一、确定可用的语法元素

• 基本语法元素
  顿号、逗号、句号、破折号、引号、冒号、括号、书名号、空格、换行

• 通用的 Markdown 语法
  标题、段落、区块引用、代码区块、加粗、斜体、列表、分割线、链接、图片、表格

• 扩展的 Markdown 语法
  内部链接、TOC 目录、脚注、删除线、TODO 列表、内嵌 ICON、LaTex 语法支持、HTML 标签 等

注：表格其实是扩展的 Markdown 语法，放在通用语法是因为基本上所有预览器都支持了表格，毕竟太重要了。

注：内部链接 和 TOC目录 也是比较重要的语法，尤其是在篇幅比较大的文档中，没有文档定位会带来极大的阅读障碍。

二、分析文档的组织结构

• 确定文档需要表达那些内容
• 分析文档不同内容之间的联系

文档表达的是什么内容，这些内容之间有什么联系？可以通过哪些语言元素来表达这些元素？下面从内容的结构属性、内容属性、位置属性三个方面进行分析。

2.1 结构属性

层级结构

B 是 A 的子概念、B 是对 A 的说明等情况下文档是层级结构。
可用的语法元素：括号、父子列表、大小标题、冒号

示例1.

• Object 类
  • Fruit 类
    • Apple 类

并行结构

当两部分内容是同一层次的概念，或者从属于同一话题，或者是某种分类的结构即为并行结构。
可用的语法元素：顿号、逗号、列表、表格、段落、标题

示例1.

即时聊天系统

功能需求

技术方案

具体实现

示例2.

函数名	说明	备注
io.open()	打开文件	与 io.close() 成对使用
io.close()	关闭文件	与 io.open() 成对使用

关联结构

B是A的额外说明，B是A的同义表达，B是A的进一步说明，这些结构称为关联结构。
可用的语法元素：分割线（分隔线没有分隔开来的部分，说明是有关联的内容）、括号、冒号

示例1.

万维网（World Wide Web，亦作 “WWW”、“Web”），是一个由许多互相链接的超文本组成的系统，通过互联网访问。

2.2 内容属性

简短与冗长

根据一段文本占用篇幅来选择语法元素。例如同样是并行结构，可以根据篇幅来确定是选用顿号还是选用列表，或者是选用段落。

示例1.

常用的编程语言有 C 语言、Java 语言、Python 语言等

示例2.

常用的语言：

• C语言，多用于偏向硬件层面的，对性能要求高的项目
• Java 语言，是世界上应用最为广泛的语言，在许多大型项目中使用
• Python 语言，被誉为万金油语言，学习门槛低，是每个人都值得学习的语言。

示例3.

介绍一下目前比较流行的几种语言的特点、应用领域和发展趋势。

C 语言

Java 语言

Python 语言

重要与次要

对于重要的内容，要选用强烈醒目的语法元素来吸引读者的注意力。重要的内容和次要的内容在语法元素的选择上要有所区分。
滥用醒目的元素会使读者感到困扰，设想一下整篇文章都采用粗体的效果。

示例1.

执行完 play 命令后，请按任意键（电源键 ( i ) 除外！）退出。

示例2.

本文档未经允许，不得转载

如需转载，请联系 [email protected]

2.3 位置属性

对于临近弱相关的内容，要想办法把他们区分开来。对于遥远但是有关联的内容，要想办法把他们联系起来。
相关的语法元素：空格，换行，分隔符，内部链接
其他技巧：序号，使用相同的语法元素

示例1.

1. if 语句

   • ...
   • ...
   • ...
   • ...

2.while 语句

---

3.for 语句

上面这个是一个反面教材，首先三者并不是并列关系，用序号联系在一起具有迷惑性。其次分割线把 while 语句 和 if 语句 分在一起，而与 for 语句割裂开来了。更合适的做法是下面这样

示例2.

条件语句

1.if 语句

• ...
• ...
• ...
• ...

循环语句

1.while 语句

2.for 语句

三、文档迭代

牢记一点，文档写作是一个艺术加工的过程，不是一蹴而就的，是一个频繁变更的过程，下面是在文档写作过程中需要注意的一些问题。

• 评估内容规模来选用相应的语法元素
• 先用低层次的元素、内容复杂化之后再使用高层次的
• 容易变动的内容最后再美化
• 借助版本控制获取随意删改的自由
• 使用尽量少的语法元素
• 在同一个文档中，每种语法元素对应一种明确的功能