为什么你应该用 Markdown 写文档？

不记得第几次安利 Markdown 了。

曾发过一篇《用Markdown写日志》。

还是决定重写一篇：

  1. 那篇重点在 HowTo ，理由一塌糊涂；这次不讨论语法，只谈为什么。
  2. 那篇重点讨论写日志（博客）；这次想讨论 Markdown 串起各种文档的可能性。
  3. 四年过去，环境和工具有了变化，像 Typora 、nodePPT 和 Marp 的出现，让 Markdown 有了更多可能，更加易用。 Typora 让写字有了仪式感和幸福感。

壹、 为什么写文档

1.1 从问题开始

成熟企业 跟 初创企业 ，关键差距是什么？

  • 设施设备？
  • 钱？
  • 人？
  • …

一个领域 专家 跟 新手 的差距呢？

  • 知识储备？
  • 经验？
  • 人脉？
  • …

钱不是 。

虽然经验告诉我们一般老江湖家底厚，但并非必然。初创企业通过融资可以获得资金，或者保不准创始人是思聪们；成熟企业也有面临资金压力时。

基于类似原因， 人脉不是 ，可以从 公开途径获取的知识 也不是。剩下的有些像是，又好像不是…


其实，老手 和 新丁 必然的差距，就是 老手经历多了 ， 积累下来 那些东西 。毕竟 新丁 之 新 ，就是 圈内（行业 / 领域）待的时间短 ，即使是富二代，有资源摆平其余各种要素，也无法凭空变出没有的经历。

可如何去量化描述 『那些东西』？是经验吗？


让我们换一组词：他们之间的差距，在于 『知识资产』 ，特别是 『过程资产』 。

知识资产（Knowledge assets）

是指企业拥有或控制的、不具有独立实物形态、对生产和服务长期发挥作用并能带来经济效益的知识。

知识资产 又叫 智力资产。只找到 MBA 智库 的狭义定义，其实个人、集体，都拥有知识资产。

过程资产（Process assets）

是指一个学习型组织在项目操作过程中所积累的无形资产。

同样来自 MBA 智库 针对企业管理的狭义定义，这个时候叫做组织过程资产。但个人也有自己的过程资产。

1.2 知识资产 与 过程资产

知识资产

  • 人力资产（HR）
  • 市场资产
  • 知识产权资产（IP）
  • 基础结构资产
    • 管理哲学 、 企业文化
    • IT系统 、 财务结构
    • …

人力资产是人才，市场资产主要以 品牌美誉度 和 企业关系 方式存在。其余知识资产 多数以某种形式的资料——主要是文件、文档的方式——存在、传播 和 传承。


过程资产

  • 规章制度、指导方针、规范标准、操作程序、工作流程、行为准则和工具方法等
  • 经验和教训，包括成文档案，也包括不成文的思想
  • 实践中形成的所有文档，包括知识资料库、文档模板、标准化表格、风险清单等
  • 实践中留下的历史信息
  • …

过程资产 首先 也是知识资产。

不过如果说 知识资产 还包含着 可以 拿来 的普适部分，那么 过程资产 就更强调实践中的积累。这种积累跟 个人、企业 自身有着高度相关性，一方面不会轻易公开，另一方面，即使公开，也要经过一定程度整理重组，才能为他人所用。

换言之，无法轻易拿来，只能自身积累。


譬如说认真学习 某知名企业 公开的工作流程，甚至有机会去参观，成果写入本企业的规章制度，可以认为获得了知识资产。但只有经过自身实践，根据实际调整，变成自己的过程资产，才可以说真正发挥作用。

在这之前，很可能水土不服，画虎不成反类犬。


1.3 为什么写文档

说了这么多，跟文档有关系吗？

有。知识资产 主要以 资料 形式存在，资料 需要文档作为载体。

特别是 过程资产，不能从外部获取，如果没有过目不忘的记忆力，就必须规范地文档化。

换言之，好好写文档，就是在积累『资产』，积累竞争力。

贰、跟文档打交道

2.1 『资产』管理

既然是资产，就要把它管理起来。

知识管理 => 信息管理 => 文档管理

三个词范围交叉，又不一样。前面范围大，越往后越具体，作为前面的开展手段。前面范围太大，我们聊聊文档的管理（其实范围也很大）。源码作为一种非常特殊的文档，自己形成了一套管理的方法（譬如 Github flow）；下面主要讨论非代码文档。当然你会发现，很多理论和工具正是来自源码管理。

『管理』过程中，我们可能面对以下一些操作：

  • 『归档』 和 『检索』 需要文件系统支持，如 Win-7 以后引入库的概念
  • 审批需要 OA 系统的导入
  • 销毁需要安全工具

等等。涉及的工具超出了文档的范围，有机会再具体讨论。

这次集中说加粗部分。

2.2 一些烦恼

记录：

不完整、不准确

事件、经过、数据、观点……都必须通过某种记录，变成素材。可以说，记录是获取文档素材的主要途径——如果再考虑到引用而来的素材，其实也来自别人的记录，那么就是唯一的途径。然而除了闭路电视全天候自动化的记录，多数的记录都面临不完整、不准确的问题。

事后的追述，既费力，也不准确。而费力不讨好又会进一步降低记录的意愿。 随时随地记录，有利于保持内容的 完整 和 有效，也减少事后整理的负担。

这需要工具足够便利，跨平台（包括移动端），快速加载打开，没有使用负担。

事实上，很多人嫌记录麻烦，写文档变成了很痛苦的例行公事。只有在面临考核时，事后回忆 甚至编造一些记录应付了事。我自己就试过月度总结不写，到检查时一口气补几个月；有见过有人没有写 commit message，事后补上。

编辑：

缺乏好用的工具；思路总被打断

好的编辑器很重要。除了编辑效率的差别，还有很重要的一点，就是内容和格式同时编辑，会引起思路的打断。

发布：

不同场景、不同用途需要不同的格式，明明差不多的内容，却整天要返工。

演示：

做 PPT / KeyNote 吃力不讨好。

版本跟踪

  • 非程序员：『版本跟踪』是什么？
  • 程序员：文档还要做版本跟踪？/ 我们已经做了。

演示上面，一个是已有的文档不能简单地转换成演示文稿；另一个是，容易在一些花俏的细节上（例如动画）花过多精力，但最终的效果也不好

版本管理 程序员一般是知道的。目前我们多数用SVN，后面有机会跟大家分享一下Git的使用。我们现在的产品文档是已经用SVN管理起来，但严格来说，没有得到很好的管理，因为你没办法像代码一样diff两个版本。因为多数文档是二进制文件，你必须两个版本都获取下来，分别打开用肉眼判断，这是很低效而且容易犯错的。

2.3 贵在坚持

高中时写代码，曾经问过为什么要写注释和文档这样的蠢话。因为当时写的东西都太简单了。

工作几年，发现无论当时多么刻骨铭心的坑，通过多少个宵，最终都会忘记。只有成文的资料真正属于 自己 和 团队。

工作前几年最可惜的事，就是因为公司繁琐的安保政策加上自己懒，太多经验没有总结记录。一定要有适合自己的工具，保持随时记录的习惯。

叁、为什么是Markdown

3.1 纯文本的威力

Markdown 是一种纯文本标记语言

*注：本章节的标题及部分内容引用自 《The Pragmatic Programmer》——Andrew Hunt & David Thomas

什么是纯文本

  • plain text (.txt)

  • Initialization file (.ini), Properties, YAML, JavaScript Object Notation (.json)

  • eXtensive Markup Language (.xml), HyperText Markup Language (.html)

  • 各种wiki (.wiki)

  • Markdown (.md), reStructuredText (.rst)

  • …


纯文本 由可打印字符组成，人可以直接阅读和理解其形式。

举例说，尽管以下内容是可打印字符，却没有意义：

1
Field19=467abe

更好的选择，是让其变得能让人理解：

1
DrawingType=UMLActivityDrawing

关键在于定义后半句：
不仅可以直接不借助任何特殊工具查看。而且是 人（脱离特定上下文也）比较容易理解 。

项目进行当中，你对项目细节如数家珍，觉得 Field19 非常清晰，467abe 意义也显而易见。但 上线一年后 再回来维护呢？一个 新同事 接手维护呢？

（一个题外话：基于类似的理由，代码中应该尽可能避免使用『魔法值』（Magic Number）。）

缺点

纯文本两个主要缺点：

  1. 跟压缩的二进制格式相比，纯文本占据 更多空间
  2. 解析处理纯文本，可能需要 更多运算

某些场景下，这两个缺点无法容忍：例如超大量需要压缩存储的数据，或者资源非常紧张的单片机。

然而随着 存储空间 和 运算能力 变得越来越廉价，这点缺点跟以下优点比起来越来越微不足道。

文本的威力

保证不过时

人能够阅读的数据形式，以及自述的数据，将比所有其他数据形式和创建它们的应用都活得更长久。

只要数据还存在，你就有可能使用它。哪怕是创建它的程序不在的时候：有可能是这个程序过时已久；也有可能这个程序刚好在这台电脑，或者你的手机上没有。

记事本打开 .doc （原本是直接贴了两行乱码在这里，但是因为会引起博客的feed解析错误，改为截图）

记事本打开 Markdown

1
2
3
##### 保证不过时
> 人能够阅读的数据形式，以及自述的数据，将比所有其他的数据形式和创建它们的应用都活得更长久。
  • 例子1 是我用记事本打开word之后任意选了两行。一个二进制文件，没有找到对应格式的编辑器，勉强打开都是这样的乱码。
  • 例子2 就是前面引用那段话。完全纯文本（基于 Markdown）。电脑或者手机有安装解析软件，你可以看到前面渲染后的效果（分别是 二号标题，段落引用）。即使不巧没有对应工具，同时完全不懂 Markdown 标签，也丝毫不影响理解 。
杠杆作用

提供锋利的『小工具』，各自专注做好一件事。

这是 Unix 设计哲学。它基于一个公共底层格式：面向行的纯文本文件 实现。每个工具专注做好一件事，然后通过 管道(pipe) 和 纯文本文件 互相打通，变成无所不能的shell脚本。

非技术背景的朋友可能还没反应过来，我换种方式复述一遍：

Unix-like 系统（包括 Unix/Linux/Mac）上的工具，就像一根根看不到内部的管道，每个专注提供一种功能：例如入口放面粉，出口就出来面包（面包机）。

如果你要进小麦出面包，没有；种子变面包，更没有。只有种子到小麦（姑且叫种植机），和小麦到面粉（磨面机）… 等等，都只专注一步。如果你需要 种子 => 三明治 ，当然也没有；但你不需要从头发明这个机器，只需要 将现有的机器，一个接一个连接在一起 。 之所以这样可行，是因为这些工具都默认接受 『一行行的纯文本』作为输入，同时输出一行行的纯文本；大家按照这个惯例行事，不必额外考虑跟其他工具的兼容——哪怕这些工具的作者互不认识，甚至写出来的时间相差几十年。

还有

  1. 假如系统崩溃，部分功能受限，如图形界面。（其实不用等系统崩溃，通过shell远程连接就没有GUI）这个时候，纯文本的优点就出来了。

    当系统崩溃时，你可能需要最小环境恢复。

  2. 在不同的系统、不同的环境之间，基于网络的异构通信、自行协商的数据交换，如果需要确保各方能用一个公共标准通信，纯文本就是这个标准（所以我们看到XML，json的流行）。

  3. 基于纯文本的版本控制，你可以追踪（diff）每个版本的修改，这才是真正的版本管理。

当一个标准可以串联起一系列工具，那么它就成为了一个支点，允许你用比较小的力气，借用现有的成果，完成复杂的工作。

纯文本就是不同时代、不同技术的最大公约数；就是标准。

3.2 内容 与 样式 的分离

两顶帽子

有两顶帽子，每次只戴其中一顶：

在修改内容时，不要理会显示的样式；

当修改样式时，不要改动内容。

两顶帽子的原则来自面向对象编程。有接口的两顶帽子、重构的两顶帽子，等等。

强调的是每次关注改变的其中一个方面，隔离互相影响的变化。同时改变多个方面容易犯错，或者打乱思路。

受Word等软件的影响，大家似乎已经把 内容编排 和 样式 混在一起了
我举个例子：
这一段的标题是一个二级标题，上面这段话，是一段引用；这是内容编排。

具体二级标题、引用文字 应该怎么显示，这是样式。

这是不同的东西：内容在编辑完之后，就相对固定下来了；而样式会因应不同的场景，不同的用途，不同的读者，有不同的需求。

像我现在做演示文稿是一种需要，同样的内容发布到博客是一种需要。演示需要的字号肯定大很多。

甚至我换一个演示环境，投影仪的对比度比显示器低，我又要改动对比度。

他们变化的频率是不一样的，应该隔离开来。样式往往到最后根据场景来定。

Write Once, Export Everywhere

Java 当年宣传，号称Write Once, Run everywhere。今天借用一下。

Markdown不仅作为纯文本，在最坏的情况下都能被记事本打开。而且由于它有大量的工具支持，可以转换为各种场景下的文档。

  • pandoc (Typora , Smark)： HTML, Word, PDF, LaTeX, Epub…
  • Marp ： PDF 演示文稿
  • nodeppt ： HTML5 演示文稿 （特效比Marp炫）
  • hexo ： 静态博客
  • gitbook ：生成电子书和文档的命令行工具，同时官方提供一个编辑器
  • Markdown here ：一个原地将 Markdown 转换成 HTML的 浏览器插件

pandoc是一个命令行工具，你当然可以敲命令使用；不过方便起见，我会推荐使用一个前端工具，首推Typora。

而当你需要在只支持 HTML 的在线编辑器使用 Markdown 时（譬如公众号后台），Markdown here 是很好的选择。

代码高亮 和 数学环境

1
2
3
4
5
#include <stdio.h>
int main(){
    printf("Hello world!");
}


$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

这两点，一般人可能没什么需求，但是数学工作者和程序员是很需要的。

以前每次用PPT，往上面贴代码的体验非常差。首先默认的字体一般不是编程用的等宽字体，要手动改。还有tab和空格的对齐，就足够折腾了。还要高亮就只能手动选中改颜色了。

但这里，只要把代码贴上去，高亮是自动完成的。

因为以前讲算法，偶尔有数学推导。Office倒是有公式编辑器，但是很难用，而且修改也不容易。

而这里，只要用Mathjax写公式就可以了。

Mathjax语法相当地直观，这里不详细展开，有需要的话，可以看我之前写的一篇文章：

Introduction to MathJax & some samples

3.3 为什么是Markdown

再问一次这个问题。

纯文本是好的，内容与样式分离是好的。但那么多纯文本的标记语言可以做到，为什么是 Markdown？

是的，不一定是Markdown。

除了 Plaintext 太弱、HTML 太繁琐 不值得选择，reStructuredText 和 asciiDoc 都是 Markdown 强有力的对手。只能说目前 Markdown 工具支持更广泛，而且（对我而言）现阶段够用又最简单。未来几年，情况可能会发生变化。

特性 Markdown rst HTML
标签 约十几种 约十几种 HTML4.1 共89个标签
标签读写 不解析也能理解读写 大部分不解析也能理解 需要层次嵌套和严谨闭合，复杂冗余
表达能力 仅覆盖常用格式，较弱；但可以直接写HTML补充，并有较多第三方增强（Mathjx，代码高亮） 支持格式比标准Markdown稍多 最强，整个互联网基本都是构建在HTML之上，前两者多数情况也是转换成HTML
工具支持 Github等代码托管，各大云笔记 不明 多数工具以HTML实现，但不提供直接编辑
格式支持 通过pandoc，能直接或间接导出几乎所有文档格式，且有较多编辑器前端可选 通过pandoc，能直接或间接导出几乎所有文档格式 能转成word、PDF等格式，但不能替换样式
总结 简单，但可拓展性强，支持广泛，工具多且开发活跃。 比Markdown稍复杂和强大，但热度不如Markdown，工具少很多。 严谨精确，适合浏览器解析，不方便一般人读写。

一些栗子

1
### 一些栗子 <!-- 二级标题 -->
  • 糖炒栗子
  • 水煮栗子
1
2
* 糖炒栗子
* 水煮栗子

维基词条

1
[维基词条](http://zh.wikipedia.org/wiki/Markdown)

更多参考

这次主要是介绍概念，教程不是重点，更多用法技巧：

最后

这个演示文稿（Presentation）完全由 Markdown 写成，使用Marp输出。

同时稍作调整后，还会发表博客、以及其他格式的文档。

如果你细心对比 博客文章 和 演示文稿，你会发现 演示文稿 上少了很多内容，这些内容是讲稿。讲稿以注释形式直接写在演示文稿里，讲的时候是对着注释讲的。

作为文章发表时，不过把 注释符 和 分页符 删掉而已，就是一个查找替换。希望未来有工具自动识别输出场景，把这一步也省略；如果迟迟不出现，我尽量抽空自己实现。

知识共享 “署名-非商业性使用-相同方式共享” 4.0 (CC BY-NC-SA 4.0)”许可协议
本文为本人原创，采用知识共享 “署名-非商业性使用-相同方式共享” 4.0 (CC BY-NC-SA 4.0)”许可协议进行许可。
本作品可自由复制、传播及基于本作品进行演绎创作。如有以上需要，请留言告知，在文章开头明显位置加上署名（Jayce Chant）、原链接及许可协议信息，并明确指出修改（如有），不得用于商业用途。谢谢合作。
详情请点击查看协议具体内容。