引言

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

總結

以上是生活随笔為你收集整理的使用纯文本方式编写软件设计文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。