使用纯文本方式编写软件设计文档

引言

软件开发过程会产生设计文档和源代码，源代码都是纯文本文件，可以方便的进行版本管理，多人协作开发。但设计文档要求图文并茂，也有很多版式要求，纯文本格式不能满足，以往多是使用word，excel等office软件编写。
word，excel虽然可以编写文档，但是文件都是二进制格式，不能进行版本管理，不方便差异对比，也不方便多人编辑和合并。而在正规的软件开发过程中，设计文档也经常需要变更和多人协作，因此如果能够使用文本格式来编写设计文档，并满足设计文档的版式和图文要求，则可以让设计文档，也能进行版本管理和多人协作。

软件设计文档的需求

软件设计文档的需求，主要就是章节排版，基本的文本格式调整，表格，图片，图片也主要是UML标准的各种图表，如流程图，序列图，类图等。随着标记语言的发展，现在已完全具备将这些内容完全文本化的条件。

Markdown格式

使用Markdown格式来编写设计文档，就基本可以满足如上需求，但是存在如下问题：

1. Markdown语法不太统一2. 很多支持编写Markdown的软件和网站都要求在线，而公司的信息安全要求，员工上网有限制，同时软件设计文档作为核心IP也不能随便发布到在线网站3. 不同Markdown编辑器对UML的功能支持，及编写语法也差异很大

因此要很好的使用Markdown在公司内部用于团队编写文档，需要提供全套的离线编辑软件，工具以及编写流程，统一大家的编辑环境

Markdown编辑环境

离线编辑软件haroopad （v0.13.2）

haroopad是一款很好用的离线Markdown编辑环境，支持多个操作系统，编写语法基本同Github兼容。其支持如下特性
- 标题
- 代码块
- mermaid语法UML图
- 流程图
- 序列图
- 甘特图
- 列表内容
- 表格
- 数学公式
- 图片
- 任务表
官网最新版是0.13.1版，这个版本对UML图支持不稳定，最好使用0.13.2版，在作者bitbucket主页可以下载
https://bitbucket.org/rhiokim/haroopad-download/downloads/

plantUML图表服务

haroopad 使用mermaid的图表文本化方案，但mermaid仅支持UML的流程图和序列图，不支持类图，如果需要支持其它的UML图表，需要使用plantUML语法编写，然后通过plantUML服务将文本转为url请求编码，嵌入到文档中，通过plantUML服务解析为图片。
如果没有外网权限，plantUML服务也可以公司内部搭建。

Astah UML编辑软件

用文本方式编写UML图，熟悉语法后其实很方便，但是初次使用可能不太习惯。为此，我们为UML编辑软件Astah，编写了插件，可以使用Astah绘制流程图和序列图，类图等UML，然后使用插件将其自动转换为mermaid或者plantUML的文本语法

有道云笔记

有道云笔记软件也具备Markdown编写功能，但需要登录账号才能使用，而且如果有网络权限，会把文档保存到云端，所以不建议使用其作为编写工具。
但是有道云笔记有一个功能，其输出内容可以拷贝，并直接粘贴到word中，可以实现markdown到word格式的转换，这对于有时候要导出word文档给客户时比较方便。
不用有道云笔记，直接使用haroopad，可以导出md文件为html。

局限

markdown编写文档效率很高，唯一一个缺点就是插入图片不方便，因为其为文本格式，不能嵌入图片，需要将图片先保存为文件，然后通过语法引入本地图片的相对路径，实现图片在文档中的显示。

结语

互联网地图事业部通过推广文本化方式写作软件设计文档，建立了多个模板和工具，在项目应用中，提高了设计文档的编写效率和管理效率。
同时，在这个自媒体时代，让大家多接触Markdown这样的工具，也有助大家持续提高自身写作能力和兴趣，学会分享自己的文字。