引言

軟件開發(fā)過程會產(chǎn)生設(shè)計文檔和源代碼，源代碼都是純文本文件，可以方便的進(jìn)行版本管理，多人協(xié)作開發(fā)。但設(shè)計文檔要求圖文并茂，也有很多版式要求，純文本格式不能滿足，以往多是使用word，excel等office軟件編寫。
word，excel雖然可以編寫文檔，但是文件都是二進(jìn)制格式，不能進(jìn)行版本管理，不方便差異對比，也不方便多人編輯和合并。而在正規(guī)的軟件開發(fā)過程中，設(shè)計文檔也經(jīng)常需要變更和多人協(xié)作，因此如果能夠使用文本格式來編寫設(shè)計文檔，并滿足設(shè)計文檔的版式和圖文要求，則可以讓設(shè)計文檔，也能進(jìn)行版本管理和多人協(xié)作。

軟件設(shè)計文檔的需求

軟件設(shè)計文檔的需求，主要就是章節(jié)排版，基本的文本格式調(diào)整，表格，圖片，圖片也主要是UML標(biāo)準(zhǔn)的各種圖表，如流程圖，序列圖，類圖等。隨著標(biāo)記語言的發(fā)展，現(xiàn)在已完全具備將這些內(nèi)容完全文本化的條件。

Markdown格式

使用Markdown格式來編寫設(shè)計文檔，就基本可以滿足如上需求，但是存在如下問題：

1. Markdown語法不太統(tǒng)一 2. 很多支持編寫Markdown的軟件和網(wǎng)站都要求在線，而公司的信息安全要求，員工上網(wǎng)有限制，同時軟件設(shè)計文檔作為核心IP也不能隨便發(fā)布到在線網(wǎng)站 3. 不同Markdown編輯器對UML的功能支持，及編寫語法也差異很大

因此要很好的使用Markdown在公司內(nèi)部用于團(tuán)隊編寫文檔，需要提供全套的離線編輯軟件，工具以及編寫流程，統(tǒng)一大家的編輯環(huán)境

Markdown編輯環(huán)境

離線編輯軟件haroopad （v0.13.2）

haroopad是一款很好用的離線Markdown編輯環(huán)境，支持多個操作系統(tǒng)，編寫語法基本同Github兼容。其支持如下特性
- 標(biāo)題
- 代碼塊
- mermaid語法UML圖
- 流程圖
- 序列圖
- 甘特圖
- 列表內(nèi)容
- 表格
- 數(shù)學(xué)公式
- 圖片
- 任務(wù)表
官網(wǎng)最新版是0.13.1版，這個版本對UML圖支持不穩(wěn)定，最好使用0.13.2版，在作者bitbucket主頁可以下載
https://bitbucket.org/rhiokim/haroopad-download/downloads/

plantUML圖表服務(wù)

haroopad 使用mermaid的圖表文本化方案，但mermaid僅支持UML的流程圖和序列圖，不支持類圖，如果需要支持其它的UML圖表，需要使用plantUML語法編寫，然后通過plantUML服務(wù)將文本轉(zhuǎn)為url請求編碼，嵌入到文檔中，通過plantUML服務(wù)解析為圖片。
如果沒有外網(wǎng)權(quán)限，plantUML服務(wù)也可以公司內(nèi)部搭建。

Astah UML編輯軟件

用文本方式編寫UML圖，熟悉語法后其實很方便，但是初次使用可能不太習(xí)慣。為此，我們?yōu)閁ML編輯軟件Astah，編寫了插件，可以使用Astah繪制流程圖和序列圖，類圖等UML，然后使用插件將其自動轉(zhuǎn)換為mermaid或者plantUML的文本語法

有道云筆記

有道云筆記軟件也具備Markdown編寫功能，但需要登錄賬號才能使用，而且如果有網(wǎng)絡(luò)權(quán)限，會把文檔保存到云端，所以不建議使用其作為編寫工具。
但是有道云筆記有一個功能，其輸出內(nèi)容可以拷貝，并直接粘貼到word中，可以實現(xiàn)markdown到word格式的轉(zhuǎn)換，這對于有時候要導(dǎo)出word文檔給客戶時比較方便。
不用有道云筆記，直接使用haroopad，可以導(dǎo)出md文件為html。

局限

markdown編寫文檔效率很高，唯一一個缺點(diǎn)就是插入圖片不方便，因為其為文本格式，不能嵌入圖片，需要將圖片先保存為文件，然后通過語法引入本地圖片的相對路徑，實現(xiàn)圖片在文檔中的顯示。

結(jié)語

互聯(lián)網(wǎng)地圖事業(yè)部通過推廣文本化方式寫作軟件設(shè)計文檔，建立了多個模板和工具，在項目應(yīng)用中，提高了設(shè)計文檔的編寫效率和管理效率。
同時，在這個自媒體時代，讓大家多接觸Markdown這樣的工具，也有助大家持續(xù)提高自身寫作能力和興趣，學(xué)會分享自己的文字。

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。