引言
軟件開發過程會產生設計文檔和源代碼，源代碼都是純文本文件，可以方便的進行版本管理，多人協作開發。但設計文檔要求圖文並茂，也有很多版式要求，純文本格式不能滿足，以往多是使用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這樣的工具，也有助大家持續提高自身寫作能力和興趣，學會分享自己的文字。