软件设计文档
内部资料 请勿外传
分享人：陈 治互联网地图事业部总经理引 言软件开发过程会产生设计文档和源代码。源代码都是纯文本文件，方便进行版本管理和多人协作开发。
但设计文档要求图文并茂，同时也有很多版式要求，纯文本格式不能满足，以往多是使用word、excel等office软件编写。word、excel虽然可以编写文档，但是文件都是二进制格式，不能进行版本管理，不方便差异对比，也不方便多人编辑和合并。
而在正规的软件开发过程中，设计文档也经常需要变更和多人协作，因此如果能够使用文本格式来编写设计文档，并满足设计文档的版式和图文要求，则可以让设计文档不仅能进行版本管理，多人协作，还能大大减少文件尺寸。
软件设计文档的需求
软件设计文档的需求，主要就是章节排版，基本的文本格式为表格和图片。图片也主要是UML标准的各种图表（如流程图、序列图、类图等）。随着标记语言的发展，现在已完全具备将这些内容完全文本化的条件。
Markdown格式
使用Markdown格式来编写设计文档就可以基本满足如上需求，但也存在如下问题：
1、Markdown语法不太统一
2、很多支持编写Markdown的软件和网站都要求在线，而根据公司信息安全管理要求对员工上网有限制，同时软件设计文档作为核心IP也不能随便发布到在线网站
3、不同Markdown编辑器对UML的功能支持及编写语法差异很大
因此想很好得让公司内部团队使用Markdown编写文档，需要提供全套的离线编辑软件，工具以及编写流程，统一的编辑环境。
Markdown编辑环境
互联网地图事业部针对业务需求，定制了一套软件设计文档的开发工具集和编写流程，完全可以满足设计文档的编写需求，而且编写效率也有效提升。这个工具集由如下软件和服务构成：
? 离线Markdown软件Haroopad
? plantUML图转换服务
? Astah UML编辑软件
? 有道云笔记
离线编辑软件Haroopad （v0.13.2）
Haroopad是一款很好用的离线Markdown编辑环境，支持多个操作系统，编写语法基本同Github兼容。其支持如下特性：
?标题
?代码块
?mermaid语法UML图
流程图
序列图
甘特图
?列表内容
?表格
?数学公式
?图片
?任务表
官网最新版是0.13.1版，该版本对UML图支持不稳定，最好使用0.13.2版。在作者bitbucket主页可以下载：https://bitbucket.org/rhiokim/haroopad-download/downloads/【点击文末“阅读原文”直达哦】
Haroopad编辑界面
plantUML图表服务
Haroopad 使用mermaid的图表文本化方案，但mermaid仅支持UML的流程图和序列图，不支持类图。如果需要支持其它的UML图表，需要使用plantUML语法编写，然后通过plantUML服务将文本转为UML请求编码，嵌入到文档中，并通过plantUML服务解析为图片。 如果没有外网权限，plantUML服务也可以公司内部搭建。
部门自建的plantUML图表转换服务
Astah UML编辑软件及自制插件
用文本方式编写UML图，熟悉语法后其实很方便，但初次使用可能不太习惯。为此，我们为UML编辑软件Astah编写了插件，可以使用Astah绘制流程图、序列图和类图等UML，然后使用插件将其自动转换为mermaid或者plantUML的文本语法。
有道云笔记
有道云笔记软件也具备Markdown编写功能，但需要登录账号才能使用，而且有网络限制，同时也会把文档保存到云端，所以不建议使用其作为编写工具。
但是有道云笔记有一个功能：其输出内容可以拷贝并直接粘贴到word中，可以实现Markdown到word格式的转换，这对于有时候要导出word文档给客户时比较方便。不用有道云笔记，直接使用Haroopad，可以导出md文件为html。
局 限
Markdown编写文档效率很高，唯一一个缺点就是插入图片不方便。因为其为文本格式，不能嵌入图片，需要将图片先保存为文件，然后通过语法引入本地图片的相对路径，实现图片在文档中的显示。
结 语互联网地图事业部通过推广文本化方式写作软件设计文档，建立了多个模板和工具。在项目应用中，提高了设计文档的编写效率和管理效率。
同时，在这个自媒体时代，让大家多接触Markdown这样的工具，也有助于持续提高自身写作能力和兴趣，学会分享自己的文字。
内部资料 请勿外传
