- 本文不涉及具体的 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.
本文档未经允许，不得转载
如需转载，请联系 tangyikejun@163.com
2.3 位置属性
对于临近弱相关的内容，要想办法把他们区分开来。对于遥远但是有关联的内容，要想办法把他们联系起来。
相关的语法元素：空格，换行，分隔符，内部链接
其他技巧：序号，使用相同的语法元素
示例1.
if 语句
- ...
- ...
- ...
- ...
2.while 语句
3.for 语句
上面这个是一个反面教材，首先三者并不是并列关系，用序号联系在一起具有迷惑性。其次分割线把 while 语句 和 if 语句 分在一起，而与 for 语句割裂开来了。更合适的做法是下面这样
示例2.
条件语句
1.if 语句
- ...
- ...
- ...
- ...
循环语句
1.while 语句
2.for 语句
三、文档迭代
牢记一点，文档写作是一个艺术加工的过程，不是一蹴而就的，是一个频繁变更的过程，下面是在文档写作过程中需要注意的一些问题。
- 评估内容规模来选用相应的语法元素
- 先用低层次的元素、内容复杂化之后再使用高层次的
- 容易变动的内容最后再美化
- 借助版本控制获取随意删改的自由
- 使用尽量少的语法元素
- 在同一个文档中，每种语法元素对应一种明确的功能
网友评论