再談如何寫好技術(shù)文檔？

1. 思維方式固化。大部分人平時(shí)代碼寫得太多，文字類型的表述又寫得太少。而代碼和文字明顯是兩種不同的思維方式，在代碼里陷得太深，不容易跳出來；

2. 本身文字表達(dá)能力有限。這個(gè)跟寫代碼一樣，有人代碼質(zhì)量高、bug少；有人水平低、bug自然就多。

以上兩點(diǎn)其實(shí)都可以通過平時(shí)多練、多寫、多梳理的方式去彌補(bǔ)，比如周期性的博客總結(jié)和記錄。但是，如果你能刻意系統(tǒng)性地去補(bǔ)充一些關(guān)于“技術(shù)型寫作”的理論知識(shí)，一定能夠事半功倍。這就像我們剛學(xué)編程時(shí)，一頓學(xué)、一頓模仿，但是總感覺缺了點(diǎn)什么，自己再努力發(fā)現(xiàn)深度還是不夠。

這時(shí)候，我們需要做的是看一本高質(zhì)量的經(jīng)典書籍，書籍能幫我們梳理知識(shí)點(diǎn)、總結(jié)各種碰到過的問題，從理論上解答我們心中各種疑惑，將之前的野路子“正規(guī)化”。

下面我根據(jù)平時(shí)的一些積累，將技術(shù)型寫作的理論知識(shí)歸納成10個(gè)要點(diǎn)。

1. 搞清楚主謂賓

2. 不濫用代詞、過渡詞和標(biāo)點(diǎn)符號(hào)

3. 多用強(qiáng)勢動(dòng)詞，少用形容詞和副詞

4. 正確使用術(shù)語

5. 正確使用段落

6. 適當(dāng)使用列表和表格

7. 一圖勝千言

8. 統(tǒng)一樣式和風(fēng)格

9. 把握好整體文檔結(jié)構(gòu)

10. 明確文檔的目標(biāo)群體

文檔主要由段落組成，段落由句子組成，而大部分句子又由“主謂賓”組成（可能有些場合省略了，但是讀者可以通過上下文輕松get到）。主謂賓是主干骨架，其他內(nèi)容可以看作是句子的修飾，主干骨架是決定句子是否垮掉的主要原因。

現(xiàn)在很多人可能已經(jīng)忘記了句子的基本構(gòu)成，畢竟以漢語為母語的人，大概率是不太會(huì)關(guān)心這些“細(xì)節(jié)”，就像說英語的國家可能不太關(guān)心am、is、are一樣，你說哪個(gè)人家都理解。

但是，文檔中的一句話讀起來是否別扭，大多數(shù)時(shí)候是由句子構(gòu)成決定的。在不考慮文檔上下文的情況下，如果一個(gè)句子能包含正確的主語、謂語和賓語（可選），那么它讀起來至少是很順口的。下面舉一個(gè)明顯搞不清主謂賓的例子：

傳統(tǒng)圖像處理算法，通過計(jì)算煙火顏色特征，極易受煙火周圍環(huán)境相近顏色干擾而造成誤檢。

盡管你能讀懂作者想要表達(dá)的意思，但是這句話讀起來還是太別扭。“傳統(tǒng)圖像處理算法”應(yīng)該算是主語，后面的“通過……”這句不完整，“極易受……干擾”這句還可以，“……造成誤檢”算是謂語賓語，但是這里用錯(cuò)了動(dòng)詞，為什么是“算法造成誤檢”，難道不是“周圍環(huán)境相近顏色干擾造成誤檢”嗎？

這句話的主干內(nèi)容是：算法極易受……影響而……。正確的表述應(yīng)該類似下面這樣：

因?yàn)閭鹘y(tǒng)圖像處理算法通過計(jì)算煙火顏色特征去識(shí)別煙火，所以它極易受煙火周圍環(huán)境相近顏色干擾而出現(xiàn)誤檢。

我們用過渡詞（因?yàn)椤浴⒃瓉淼木渥硬鸪闪饲昂髢蓚€(gè)部分，前面部分的主語是“傳統(tǒng)圖像處理算法”，謂賓是“識(shí)別煙火”；后半部分的主語是“它”，謂賓是“出現(xiàn)誤檢”。經(jīng)過調(diào)整后，前后兩個(gè)部分的主語是同一個(gè)：傳統(tǒng)圖像處理算法。下面再直觀看一下修改之后的句子主干骨架：

<因?yàn)?gt;<傳統(tǒng)圖像處理算法>通過計(jì)算煙火顏色特征去<識(shí)別煙火>， <所以><它>極易受煙火周圍環(huán)境相近顏色干擾而<出現(xiàn)誤檢>。

如果你覺得用“因?yàn)椤浴辈惶?，那么可以再換一種表述：

傳統(tǒng)圖像處理算法通過計(jì)算煙火顏色特征去識(shí)別煙火，煙火周圍環(huán)境相近顏色的干擾極易造成誤檢。

第一句還是跟之前一樣，主語是“傳統(tǒng)圖像處理算法”，第二句主語變成了“干擾”，謂賓是“造成誤檢”。下面我們直觀地看一下修改之后的句子主干骨架：

<傳統(tǒng)圖像處理算法>通過計(jì)算煙火顏色特征去<識(shí)別煙火>， 煙火周圍環(huán)境相近顏色的<干擾>極易<造成誤檢>。

最后再舉一個(gè)錯(cuò)誤的例子：

由于誤報(bào)率與漏報(bào)率很高，因此不管是否有真實(shí)事件發(fā)生都會(huì)去留意，也會(huì)有規(guī)定的日程定點(diǎn)巡查視頻任務(wù)。

上面這個(gè)句子的作者完全沒搞懂誰是主語，誰是謂語。感興趣的童鞋可以試著修改一下，改成你認(rèn)為正確的表述。

不濫用代詞和過渡詞

中文文檔中的代詞主要有：你、我、他、她、它、其、前者、后者、這樣、那樣、如此等等，過渡詞主要有：因?yàn)?所以、不但/而且、首先/然后等等。下面這張表格列舉了一些常見的代詞和過渡詞及其常用場合：

表2-1 代詞和過渡詞舉例

代詞和過渡詞就像標(biāo)點(diǎn)符號(hào)一樣，容易被濫用。代詞濫用主要體現(xiàn)在作者在使用它們的時(shí)候并沒有搞清楚它們代表的究竟是誰，是前一句的主語、還是前一句的賓語或者干脆是前一整句話？

過渡詞濫用主要體現(xiàn)在作者在使用它們的時(shí)候并沒有搞清楚前后兩句話的邏輯關(guān)系，是遞進(jìn)還是轉(zhuǎn)折或者是因果？（過渡詞濫用頻率要低很多，畢竟搞清楚前后句子邏輯的難度要小）接下來舉幾個(gè)濫用代詞和過渡詞的例子：

C++語言發(fā)明于1980年代，它支持“指針”和“面向?qū)ο螅∣bject-Oriented）”兩個(gè)特性，其價(jià)值在計(jì)算機(jī)編程語言歷史上數(shù)一數(shù)二。

上面這個(gè)句子中出現(xiàn)了兩個(gè)代詞“它”和“其”，拋開句子內(nèi)容本身對錯(cuò)不論，第二個(gè)代詞指向的對象其實(shí)并不明確，“其”指的是“指針”、“面向?qū)ο蟆边€是“C++語言”？或者是指“C++語言同時(shí)支持……兩個(gè)特性”這個(gè)陳述？像這種有歧義的場合，我們應(yīng)該少用代詞，盡量用具體的主語去代替：

C++語言發(fā)明于1980年代，它支持“指針”和“面向?qū)ο螅∣bject-Oriented）”兩個(gè)特性，C++的價(jià)值在計(jì)算機(jī)編程語言歷史上數(shù)一數(shù)二。

如果你一定要用代詞，那么調(diào)整一下可能更好：

C++語言發(fā)明于1980年代，它同時(shí)支持“指針”和“面向?qū)ο螅∣bject-Oriented）”兩個(gè)特性，這個(gè)價(jià)值在計(jì)算機(jī)編程語言歷史上數(shù)一數(shù)二。

再讀一讀，你是不是沒有感覺到歧義了？我們在“支持”前面增加了一個(gè)“同時(shí)”，然后將代詞換成了“這個(gè)”，現(xiàn)在這個(gè)代詞指的是“C++語言同時(shí)支持...兩個(gè)特性”這個(gè)陳述，修改后整個(gè)句子的意思更明確。

我們再來看另外一個(gè)濫用代詞的例子：

該模塊主要負(fù)責(zé)對視頻進(jìn)行解碼，輸出單張YUV格式的圖片，并對輸出的圖片進(jìn)行壓縮和裁剪，前者基于Resize方法來完成，后者基于Crop()方法完成。

對于大部分人來講，上面這段沒什么問題。代詞“前者”指的是壓縮、“后者”指的是裁剪，原因很簡單，因?yàn)閱卧~Resize對應(yīng)的是壓縮、單詞Crop對應(yīng)的是裁剪。

但是這段話如果拿給沒有任何知識(shí)背景的人去讀（大概率可能是找不到這種人），恐怕會(huì)存在歧義，主要原因是代詞前面提到了很多東西，“前者”和“后者”指向不明確，到底是指“解碼”、“輸出單張圖片”還是后面的“壓縮”和“裁剪”？下面這樣調(diào)整后，整段話的意思更加明確：

該模塊主要負(fù)責(zé)對視頻進(jìn)行解碼，輸出單張YUV格式的圖片，并對輸出的圖片進(jìn)行壓縮和裁剪，壓縮基于Resize方法來完成，裁剪基于Crop()方法完成。

我們?nèi)サ袅舜~，直接用具體的主語來代替，句子意思非常明確。如果你一定要使用代詞，那么也可以這樣調(diào)整：

該模塊主要負(fù)責(zé)對視頻進(jìn)行解碼，輸出單張YUV格式的圖片。同時(shí)，它還對輸出的圖片進(jìn)行壓縮和裁剪，前者基于Resize()方法完成，后者基于Crop()方法完成。

上面這段話還是使用了代詞“前者”/“后者”，但是我們修改了標(biāo)點(diǎn)符號(hào)，并且增加了一個(gè)過渡詞“同時(shí)……”，這樣做的目的是讓讀者知道雖然整段話說的是同一個(gè)東西，但是前后的句子已經(jīng)分開了，為我們后面使用代詞做好準(zhǔn)備。

好的，現(xiàn)在我們來總結(jié)一下在技術(shù)型文檔編寫過程中使用代詞時(shí)的一些有價(jià)值經(jīng)驗(yàn)：

1. 代詞可以指它前面出現(xiàn)過的名詞、短語甚至整個(gè)句子，但是一定是前面出現(xiàn)過的；

2. 代詞的位置和它要指向的目標(biāo)最好不要隔得太遠(yuǎn)，1~3句話之內(nèi)，超過就不要用了；

3. 代詞的作用是減少小范圍內(nèi)某些詞匯或句子重復(fù)出現(xiàn)的頻率，要用到恰到好處；

4. 代詞前面出現(xiàn)的混淆目標(biāo)如果太多，一定要重新調(diào)整句子，確保代詞指向無歧義。

不濫用標(biāo)點(diǎn)符號(hào)

接下來我們再看另一個(gè)，標(biāo)點(diǎn)符號(hào)的濫用要普遍很多，其主要原因是：標(biāo)點(diǎn)符號(hào)的使用并沒有非常明確的對錯(cuò)之分。至少對大部分人而言，使用句號(hào)還是逗號(hào)其實(shí)并沒有什么嚴(yán)格的評(píng)判標(biāo)準(zhǔn)，只要不出現(xiàn)“一逗到底”的極端情況，其余大概率都OK。下面這張表格是我根據(jù)以往經(jīng)驗(yàn)，總結(jié)出來的應(yīng)用于技術(shù)型寫作時(shí)中文標(biāo)點(diǎn)符號(hào)使用規(guī)則：

表2-2 常用標(biāo)點(diǎn)符號(hào)

上面這張表格基本涵蓋了常用的中文標(biāo)點(diǎn)符號(hào)，其中有一小部分在技術(shù)型文檔中不太常見，比如感嘆號(hào)、破折號(hào)，這些符號(hào)多多少少帶有某種感情色彩，不太適合用于技術(shù)型文檔編寫。前面已經(jīng)簡單概括了一下各個(gè)符號(hào)的使用場合，下面挑幾個(gè)容易出錯(cuò)的再一一詳細(xì)說明：

C++語言發(fā)明于1980年代，它衍生自C語言，主要引入了“面向?qū)ο螅∣bject-Oriented）”思想，面向?qū)ο笏枷霃?qiáng)調(diào)對數(shù)據(jù)的封裝和對功能的復(fù)用，此特性有利于開發(fā)者對代碼的維護(hù)和擴(kuò)展，目前，大部分計(jì)算機(jī)編程語言已經(jīng)支持了面向?qū)ο筇匦浴?/span>

上面這段話屬于典型的“一逗到底”的例子。作者從C++語言說到了面向?qū)ο笏枷?，最后總結(jié)大部分計(jì)算機(jī)編程語言都支持面向?qū)ο?。我們?nèi)绻麑⒄卧挷痖_來看，其實(shí)它想表述的是3個(gè)內(nèi)容，每個(gè)內(nèi)容之間最好使用句號(hào)，停頓時(shí)間稍長一些。我們調(diào)整之后的效果是：

C++語言發(fā)明于1980年代，它衍生自C語言，主要引入了“面向?qū)ο螅∣bject-Oriented）”思想。面向?qū)ο笏枷霃?qiáng)調(diào)對數(shù)據(jù)的封裝和對功能的復(fù)用，此特性有利于開發(fā)者對代碼的維護(hù)和擴(kuò)展。目前，大部分計(jì)算機(jī)編程語言已經(jīng)支持了面向?qū)ο筇匦浴?/span>

接下來我們再看看分號(hào)的使用。根據(jù)我個(gè)人經(jīng)驗(yàn)，分號(hào)常用在列表場合，下面舉一個(gè)例子說明：

下面是“將大象裝入冰箱”的具體步驟：

1. 打開冰箱門；

2. 將大象裝進(jìn)冰箱；

3. 關(guān)上冰箱門。

上面是一個(gè)有序列表，列表中的各項(xiàng)內(nèi)容是一個(gè)短語。當(dāng)列表中各項(xiàng)內(nèi)容是短語或者句子的時(shí)候，除最后一項(xiàng)之外其余項(xiàng)目結(jié)尾一般都使用分號(hào)（注意，同一個(gè)列表中各項(xiàng)的格式最好都保持一致，要么都是短語，要么都是單個(gè)的名詞，這個(gè)后面專門講列表的時(shí)候會(huì)提到）。如果列表中各項(xiàng)內(nèi)容只是一個(gè)名詞時(shí)，那么結(jié)尾就可以不用標(biāo)點(diǎn)符號(hào)：

下面是“可以被裝進(jìn)冰箱”的動(dòng)物：

• 狗子

• 大象

• 猴子

• 鸚鵡

上面是一個(gè)無序列表，列表中的各項(xiàng)內(nèi)容是一個(gè)名詞，這時(shí)候名詞結(jié)尾處不需要添加任何標(biāo)點(diǎn)符號(hào)。

我們最后再來看一下小括號(hào)的使用場合。在技術(shù)型文檔中，小括號(hào)主要用于對前面的名詞、短語或者句子進(jìn)行補(bǔ)充說明，比如當(dāng)文檔中出現(xiàn)縮寫詞匯時(shí)，我們會(huì)在它的后面增加一個(gè)小括號(hào)，在括號(hào)里面注明該縮寫詞匯的全稱。下面舉一個(gè)使用小括號(hào)對縮寫詞匯解釋說明的例子：

API（Application Program Interface）是系統(tǒng)對外提供的訪問接口，使用者可以按照API文檔中的接口定義去訪問系統(tǒng)中的數(shù)據(jù)，并與它做一些交互。

上面這段話主要講API是什么、可以干什么。它是Application Program Interface三個(gè)單詞的簡稱，為了讓讀者更清楚該術(shù)語的定義，作者可以選擇在第一個(gè)“API”出現(xiàn)的位置增加一個(gè)小括號(hào)，并將術(shù)語全稱補(bǔ)充進(jìn)來，之后的整個(gè)文檔無需再重復(fù)該操作（后面會(huì)單獨(dú)提到術(shù)語全稱和簡稱的運(yùn)用規(guī)則）。

除了能對縮寫詞匯進(jìn)行解釋說明之外，小括號(hào)還可以用于對前面整個(gè)句子進(jìn)行補(bǔ)充說明，再看下面這個(gè)例子：

它是Application Program Interface三個(gè)單詞的簡稱，為了讓讀者更清楚該術(shù)語的定義，作者可以選擇在第一個(gè)“API”出現(xiàn)的位置增加一個(gè)小括號(hào)，并將術(shù)語全稱補(bǔ)充進(jìn)來，之后的整個(gè)文檔無需再重復(fù)該操作（后面會(huì)單獨(dú)提到術(shù)語全稱和簡稱的運(yùn)用規(guī)則）。

上面這段話其實(shí)前面已經(jīng)出現(xiàn)過，最后小括號(hào)里面的內(nèi)容主要是為了對它前面一句話進(jìn)行補(bǔ)充。如果補(bǔ)充性說明內(nèi)容太長，比如要好幾句話才能起到補(bǔ)充的作用，那么這個(gè)時(shí)候我們就不應(yīng)該再使用小括號(hào)了，可以考慮調(diào)整句子結(jié)構(gòu)，然后將補(bǔ)充性的內(nèi)容當(dāng)作段落主體的一部分。

關(guān)于代詞、過渡詞以及標(biāo)點(diǎn)符號(hào)濫用的內(nèi)容就講到這里，其中有一些內(nèi)容是我個(gè)人的寫作喜好，其實(shí)并沒有非常明確的對錯(cuò)之分，比如前面講到列表中分號(hào)的使用，很多人這時(shí)候可能選擇使用句號(hào)。

大家可以根據(jù)自己的判斷去處理這種模棱兩可的場景，當(dāng)然一些比較確定的規(guī)則，比如當(dāng)列表項(xiàng)只有名詞的時(shí)候，列表項(xiàng)結(jié)尾不要使用任何標(biāo)點(diǎn)符號(hào)，這一點(diǎn)還是比較確定的。

強(qiáng)勢動(dòng)詞和主動(dòng)語句

很多人可能第一次聽到“強(qiáng)勢動(dòng)詞”這個(gè)說法，陌生還難以理解。如果將它翻譯成英文，對應(yīng)的單詞應(yīng)該是“Strong Verbs”，意思是強(qiáng)有力的動(dòng)詞，你可以理解為：聽起來動(dòng)作幅度大、沖擊力強(qiáng)的那一類動(dòng)詞。打個(gè)比方，假如“走”是弱勢動(dòng)詞，那么“跳”就是強(qiáng)勢動(dòng)詞；假如拿刀“切”是弱勢動(dòng)詞，那么拿刀“砍”就是強(qiáng)勢動(dòng)詞。下面這張表格列舉了一些強(qiáng)勢/弱勢動(dòng)詞的例子：

表3-1 強(qiáng)勢/弱勢動(dòng)詞對比

上面列出了10對強(qiáng)勢/弱勢動(dòng)詞，我們觀察可以發(fā)現(xiàn)：弱勢動(dòng)詞一般無法正確表達(dá)問題/事情的真實(shí)情況。在技術(shù)型文檔編寫過程中，雖然我們不能借助詞匯使用、句子構(gòu)成以及標(biāo)點(diǎn)符號(hào)等手段去傳遞感情傾向，但是也不能掩蓋真實(shí)準(zhǔn)確的內(nèi)容表達(dá)。

在提到強(qiáng)勢動(dòng)詞時(shí)，我們還要注意“主動(dòng)語句”和“被動(dòng)語句”的區(qū)別。在技術(shù)型文檔編寫過程中，應(yīng)該盡量少使用被動(dòng)語句。下面這張表格列舉了一些主動(dòng)/被動(dòng)語句的例子：

表3-2 主動(dòng)/被動(dòng)語句對比

上面表中第5項(xiàng)（帶*號(hào)）嚴(yán)格來講不算被動(dòng)語句，但是在技術(shù)型寫作過程中，我們應(yīng)該避免使用“……是……的。”這種句式，該句式太過口語化。盡量少用被動(dòng)語句的原因有以下三個(gè)：

1. 讀起來麻煩。讀者讀到被動(dòng)語句時(shí)，需要先在腦子里將其轉(zhuǎn)換一下再去理解；

2. 難以理解。讀者有時(shí)候很難分清被動(dòng)語句中的真實(shí)主語（甚至可能省略了主語）；

3. 字?jǐn)?shù)多。被動(dòng)語句一般更長、字?jǐn)?shù)更多。

那么被動(dòng)語句是不是完全不讓用了呢？當(dāng)然不是。仔細(xì)的讀者可能已經(jīng)觀察到了前面在舉例的時(shí)候我們有這樣一段話：

C++語言<發(fā)明于>1980年代，它支持“指針”和“面向?qū)ο螅∣bject-Oriented）”兩個(gè)特性，C++的價(jià)值在計(jì)算機(jī)編程語言歷史上數(shù)一數(shù)二。

上面第一句中的“……于”其實(shí)就是被動(dòng)語句，像“C++語言發(fā)明于……”、“該文檔編輯于……”這些都算被動(dòng)語句，由于賓語（這里是C++語言）更重要，所以默認(rèn)省略了真實(shí)主語（某某發(fā)明C++語言，可是某某在這里不太重要）。這類句子結(jié)構(gòu)有一個(gè)特點(diǎn)就是：賓語比真實(shí)主語重要，所以放到句子的開頭位置。

少用形容詞和副詞

技術(shù)型文檔講究的是一個(gè)“準(zhǔn)”字，它不像小說、散文之類的文學(xué)作品帶有很強(qiáng)的感情色彩，也不同于網(wǎng)絡(luò)博客可以摻雜一些非正式詞匯，更不能跟Marketing Speech（營銷話語）一樣常常夸大其詞。為了做好前面說的“準(zhǔn)”，技術(shù)型文檔應(yīng)該盡量少用形容詞和副詞，因?yàn)檫@些詞語大部分都屬于“主觀”表達(dá)。下面舉幾個(gè)使用形容詞和副詞的例子：

為了保證系統(tǒng)運(yùn)行更高效，他們嘗試盡可能壓縮圖片尺寸，事實(shí)證明這個(gè)嘗試非常成功。這樣的工作看似簡單，卻蘊(yùn)含著高技術(shù)含量。

上面這段話使用了好幾個(gè)副詞和形容詞，比如“盡可能”、“非常”、“高”。如果是技術(shù)型文檔，這段話建議調(diào)整為：

為了提高系統(tǒng)運(yùn)行效率，他們將圖片尺寸壓縮到原來的1/3，系統(tǒng)響應(yīng)速度提升2倍。

我們用具體的數(shù)值替換了原來的形容詞和副詞，并且直接刪掉了最后一句話，最后一句話在技術(shù)型文檔中起不到任何作用。下面這張表格列舉了部分形容詞和副詞使用不恰當(dāng)?shù)膱龊希?/span>

表3-3 形容詞/副詞使用不恰當(dāng)舉例

最后，我們來總結(jié)一下：

1. 優(yōu)先使用方便讀者閱讀理解的動(dòng)詞和句式（強(qiáng)勢動(dòng)詞和主動(dòng)語句）；

2. 盡量少用形容詞和副詞，用具體數(shù)值代替、或者調(diào)整句子表述。

這里提到的術(shù)語分兩種：一種是計(jì)算機(jī)領(lǐng)域通用的專業(yè)術(shù)語，像SDK、面向?qū)ο?、TCP/IP、微服務(wù)等等這些名詞，它們基本已經(jīng)被大眾接受和理解，我們在編寫文檔的時(shí)候不能隨意再重新去命名、調(diào)整或者改變拼寫（將“TCP/IP”寫成“Tcp/ip”）。

另外一種是當(dāng)前文檔需要定義的術(shù)語，這種術(shù)語只有在當(dāng)前文檔上下文中才有效。我們在編寫技術(shù)型文檔時(shí)，通過自己的判斷，如果認(rèn)為文檔讀者缺乏對相關(guān)術(shù)語（不管是前面哪一種）的理解，我們都應(yīng)該在文檔靠前位置給出對術(shù)語的解釋說明，也就是我們平時(shí)文檔中常見的“名詞解釋”。

表4-1 名詞解釋舉例（*為自定義術(shù)語）

有些文檔可能篇幅比較短，并不是傳統(tǒng)意義上的需求設(shè)計(jì)類文檔，比如對某個(gè)線上問題分析的結(jié)果匯報(bào)、對某個(gè)模型檢測效果的驗(yàn)證報(bào)告、或者研發(fā)階段性的工作總結(jié)。這些文檔由于本身內(nèi)容就不多，大部分可能直接進(jìn)入主題，這時(shí)候如果還要在文檔中專門增加一塊名詞解釋的版塊（并且總共也就一兩個(gè)術(shù)語），就顯得比較突兀。

另外一種對術(shù)語進(jìn)行解釋說明的方式是用我們前面提到的小括號(hào)，我們可以在術(shù)語后面增加一個(gè)小括號(hào)，然后在括號(hào)里添加補(bǔ)充說明。這種方式很便捷，但是只適合簡單的場景，比如在小括號(hào)里面補(bǔ)充術(shù)語的全稱或者簡稱，或者只做簡單的解釋說明。如果對一個(gè)術(shù)語的解釋內(nèi)容很長，就不太適合用這個(gè)方法，下面舉一個(gè)錯(cuò)誤的例子：

當(dāng)視頻離線時(shí)，F(xiàn)VM（Front Video Manager，前端視頻管理服務(wù)，負(fù)責(zé)視頻接入、分發(fā)等業(yè)務(wù)。）會(huì)產(chǎn)生一條告警記錄，并存入節(jié)點(diǎn)數(shù)據(jù)庫。

上面這個(gè)術(shù)語解釋內(nèi)容太長，不太適合使用小括號(hào)的方式，這種情況要么在文檔正文中專門對FVM進(jìn)行解釋，要么在小括號(hào)中只給出FVM的英文全稱即可：

當(dāng)視頻離線時(shí)，F(xiàn)VM（Front Video Manager）會(huì)產(chǎn)生一條告警記錄，并存入節(jié)點(diǎn)數(shù)據(jù)庫。

使用小括號(hào)去做術(shù)語解釋還需要注意一點(diǎn)的是：只需要在術(shù)語第一次出現(xiàn)的時(shí)候做一次解釋即可，不需要重復(fù)多次。下面舉一個(gè)重復(fù)的錯(cuò)誤例子：

當(dāng)視頻離線時(shí)，F(xiàn)VM（Front Video Manager）會(huì)產(chǎn)生一條告警記錄，并存入節(jié)點(diǎn)數(shù)據(jù)庫。之后節(jié)點(diǎn)數(shù)據(jù)庫會(huì)將該條告警記錄同步到平臺(tái)數(shù)據(jù)庫，平臺(tái)FVM（Front Video Manager）檢測到有新的告警記錄時(shí)，會(huì)通過消息中間件通知業(yè)務(wù)系統(tǒng)，業(yè)務(wù)系統(tǒng)隨后將告警信息以短信（或釘釘）的方式通知到用戶。

上面對術(shù)語FVM的解釋重復(fù)了兩次，這種做法是錯(cuò)誤的，第二次我們可以直接去掉。

有些術(shù)語存在全稱和簡稱，我們熟悉的SDK全稱是“Software Development Kit”，但是現(xiàn)在基本沒有人再去使用它的全稱。像這種簡稱已經(jīng)被大眾熟知的術(shù)語，我們就不能再標(biāo)新立異的去用它的全稱。

另外一些在文檔中自定義的術(shù)語，文檔作者為了便于閱讀可能也會(huì)提供一個(gè)簡寫的版本，在這種情況下，文檔前后應(yīng)該保持一致，即：要么整篇文檔都用全稱，要么都用簡稱，盡量做到一致。下面舉一個(gè)全稱簡稱使用不一致的例子：

IVA（Intelligent Video Analytics，智能視頻分析）服務(wù)主要負(fù)責(zé)視頻解碼、模型推理、目標(biāo)跟蹤以及目標(biāo)行為分析，該服務(wù)是整個(gè)系統(tǒng)中最復(fù)雜的一個(gè)模塊。智能視頻分析服務(wù)由張三團(tuán)隊(duì)開發(fā)完成，一共耗時(shí)6個(gè)月，人力成本開銷120萬。

上面這段話中，前半部分作者使用“IVA”簡稱（小括號(hào)中做了全稱說明），但是在后面一句話中作者又使用了全稱“智能視頻分析”，這種做法沒有遵循統(tǒng)一原則。不僅同一段落應(yīng)該保持統(tǒng)一，整篇文檔也應(yīng)該做到統(tǒng)一，術(shù)語在文檔中第一次出現(xiàn)時(shí)是簡稱，那么整篇文檔都應(yīng)該用簡稱，反之亦然。

最后我們來總結(jié)一下，在技術(shù)型文檔中使用術(shù)語時(shí)需要注意的一些事項(xiàng)：

1. 文檔讀者不熟悉的術(shù)語（包括通用術(shù)語和文檔自定義術(shù)語）都應(yīng)該有解釋說明；

2. 小括號(hào)只適合簡短的術(shù)語解釋場合，括號(hào)里的內(nèi)容不能太長（一兩句短語之內(nèi)）；

3. 任何方式的術(shù)語解釋只需要有一次即可（術(shù)語第一次出現(xiàn)時(shí)），不要解釋多次；

4. 術(shù)語的全稱和簡稱要保持使用一致，要么整篇文檔都用全稱、要么都用簡稱；

5. 對于計(jì)算機(jī)領(lǐng)域的通用專業(yè)術(shù)語，需要沿用主流用法，不要隨意再去調(diào)整。

單一職責(zé)

與面向?qū)ο缶幊讨小邦惖膯我宦氊?zé)原則”一樣，文檔中的句子（特指以句號(hào)結(jié)尾的一句話）、段落也應(yīng)該遵循“單一職責(zé)原則”。前面講標(biāo)點(diǎn)符號(hào)的時(shí)候已經(jīng)提到過，同一段話中前后關(guān)聯(lián)性不大的兩句話之間用句號(hào)，這樣可以保證每句話想要表達(dá)的是相對獨(dú)立的內(nèi)容。

段落也一樣，一個(gè)段落只陳述一個(gè)主題，可以保證段落的句子不會(huì)太多、內(nèi)容不會(huì)太長，便于讀者閱讀和理解。下面舉一個(gè)段落使用錯(cuò)誤的例子：

Excel提供一個(gè)組織數(shù)據(jù)的高效方法。我們可以將Excel想象成一個(gè)有行和列的二維表格，每一行代表一個(gè)獨(dú)立的實(shí)體，每一列代表該實(shí)體的不同屬性。Excel還具備數(shù)學(xué)功能，比如計(jì)算平均值和方差等數(shù)學(xué)操作。如果你想使用Excel來記錄圖書信息，那么每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價(jià)格以及出版社等等信息。

上面這段話的第一句已經(jīng)明確了段落主題：Excel能高效地組織數(shù)據(jù)?？墒?，這段話中間卻穿插了一個(gè)不相干的句子，說Excel具備數(shù)學(xué)功能，能夠做一些數(shù)學(xué)操作，這句話顯然跟本段主題不一致，我們需要將其去掉：

Excel提供一個(gè)組織數(shù)據(jù)的高效方法。我們可以將Excel想象成一個(gè)有行和列的二維表格，每一行代表一個(gè)獨(dú)立的實(shí)體，每一列代表該實(shí)體的不同屬性。如果你想使用Excel來記錄圖書信息，那么每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價(jià)格以及出版社等等信息。

好的開頭語

除了要保證段落的“單一職責(zé)”之外，我們還需要給每個(gè)段落一句“好的”開頭語。那么什么是好的開頭語呢？好的開頭語要能讓讀者讀完之后就能猜到文檔作者在本段中想要陳述的主題，其實(shí)就是概括性的句子。

還是以上面那段話為例子，它的第一句話“Excel提供一個(gè)組織數(shù)據(jù)的高效方法”其實(shí)就是很好的開頭語，它提示本段內(nèi)容主要講Excel如何高效地組織數(shù)據(jù)。如果我們將上面那段話的開頭調(diào)整一下，那么效果明顯就差了很多：

Excel由許許多多的單元格組成，每個(gè)單元格可以包含不同的內(nèi)容。我們可以將Excel想象成一個(gè)有行和列的二維表格，每一行代表一個(gè)獨(dú)立的實(shí)體，每一列代表該實(shí)體的不同屬性。如果你想使用Excel來記錄圖書信息，那么每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價(jià)格以及出版社等等信息。

讀者讀完上面第一句話后，可能還是很懵，需要讀完整段話才能明白文檔作者在本段中想要表達(dá)的意思。段落的開頭語可以通過提煉段落內(nèi)容得到，我們可以在段落寫完之后回過頭提煉一句話作為本段的開頭語，下面這段話描述代碼中循環(huán)語句的作用：

目前幾乎所有的計(jì)算機(jī)編程語言都支持循環(huán)語句，例如，我們可以編寫代碼來判斷一個(gè)用戶命令行輸入是否等于“quit”（退出命令），如果需要判斷100萬次，那就創(chuàng)建一個(gè)循環(huán)，讓判斷邏輯代碼運(yùn)行100萬次。

上面的這段話本身沒什么問題，主要介紹循環(huán)語句的功能和應(yīng)用場合。但是如果我們提煉一下，在段落開頭增加一個(gè)更好的開頭語，效果可能會(huì)提升很多：

循環(huán)語句會(huì)多次運(yùn)行同一個(gè)代碼塊，直到不再滿足循環(huán)條件為止。目前幾乎所有的計(jì)算機(jī)編程語言都支持循環(huán)語句，例如，我們可以編寫代碼來判斷一個(gè)用戶命令行輸入是否等于“quit”（退出命令），如果需要判斷100萬次，那就創(chuàng)建一個(gè)循環(huán)，讓判斷邏輯代碼運(yùn)行100萬次。

上面開頭第一句話就說清楚了循環(huán)結(jié)構(gòu)的特點(diǎn)，讀者讀完第一句話基本就知道整段內(nèi)容要講什么。一個(gè)好的開頭語能夠節(jié)省讀者的時(shí)間，因?yàn)椴⒉皇敲總€(gè)讀者都有興趣去閱讀整段的內(nèi)容，開頭語可以給讀者“是否繼續(xù)讀下去”一個(gè)參考。

控制段落長度

控制段落長度并沒有一個(gè)明確的標(biāo)準(zhǔn)，它只是一個(gè)非常主觀的說法。如果文檔中某個(gè)段落內(nèi)容太長（比如那種一段話就占半頁Word），作者自己應(yīng)該反復(fù)閱讀幾次再對段落做一些精簡，這樣既可以節(jié)省讀者的時(shí)間，大概率也能提升意思表達(dá)的準(zhǔn)確性。

同樣，也不太建議文檔頻繁出現(xiàn)小段落，比如整段內(nèi)容只有一兩句話那種，這個(gè)時(shí)候可以考慮段落合并或者稍微擴(kuò)充一下內(nèi)容。

最后我們來總結(jié)一下，在技術(shù)型文檔中如何正確使用段落：

1. 一個(gè)段落只負(fù)責(zé)講一個(gè)內(nèi)容，兩個(gè)不同的主題應(yīng)該拆分成兩個(gè)段落去陳述；

2. 盡量為每個(gè)段落增加一個(gè)“好的”開頭語，能夠清晰表達(dá)（或暗示）本段的主題；

3. 要控制好段落內(nèi)容長短，“不長不短”根據(jù)自己經(jīng)驗(yàn)（比如不超5~7個(gè)句子）。

文字相對來講其實(shí)是一種效率比較低的表達(dá)方式。如果你想讓人快速地去理解你要表達(dá)的意思，圖片應(yīng)該是最好的一種方式，但是圖片有一個(gè)缺點(diǎn)就是：有時(shí)候它只能從宏觀上去表達(dá)，無法體現(xiàn)其中細(xì)節(jié)。

當(dāng)我們想要盡可能直觀地去陳述內(nèi)容，又想盡可能多的包含細(xì)節(jié)時(shí)，我們可以考慮使用列表或者表格。有些讀者非常抵觸大段大段的文字（尤其在技術(shù)型文檔中），一種改進(jìn)方法是前面提到的“控制段落長度”，盡量讓段落內(nèi)容精簡、單一；再一個(gè)就是看看段落內(nèi)容是否能以列表或者表格的方式去呈現(xiàn)，這種方式可以給人“嚴(yán)謹(jǐn)、清晰”的感覺。

使用列表

列表簡單來講就是將你原來用段落方式呈現(xiàn)的內(nèi)容改用項(xiàng)目（Item）的方式去呈現(xiàn)，一般它主要用于枚舉、過程描述或者要點(diǎn)歸納等場合。列表中的各項(xiàng)可以是名詞、短語，甚至是句子，各項(xiàng)目之間有嚴(yán)格順序要求的列表叫“有序列表”，相反并沒有嚴(yán)格順序要求的列表叫“無序列表”。下面是以段落的方式陳述小張今天所做的事情：

白天在公司上班期間，小張一共修復(fù)了7個(gè)bug，做了3個(gè)代碼合并（評(píng)審），并和項(xiàng)目經(jīng)理討論了前天提的新需求。晚上回到家后，小張先做飯，然后給兒子洗澡，23:30上床睡覺。

上面這段話本身沒什么問題，用了合理的標(biāo)點(diǎn)符號(hào)和過渡詞，讀起來清晰明了。但是，如果在技術(shù)型文檔編寫中，能將這段話改用列表的方式呈現(xiàn)，起到的效果會(huì)更好：

小張白天在公司：

• 修復(fù)了7個(gè)bug；

• 做了3個(gè)代碼合并（評(píng)審）；

• 和項(xiàng)目經(jīng)理討論前天提的新需求。

晚上回到家后：

1. 做晚飯；

2. 給兒子洗澡；

3. 23:30上床睡覺。

我們將原來的一段話拆成了兩個(gè)列表，并在每個(gè)列表前面做了一個(gè)“引入說明”（以冒號(hào)結(jié)束），介紹了接下來列表的背景上下文。第一個(gè)列表是無序列表，因?yàn)樵牟]有突出強(qiáng)調(diào)小張白天在公司每項(xiàng)工作之間的前后關(guān)系（無順序要求），只是一個(gè)歸納統(tǒng)計(jì)；第二個(gè)列表是一個(gè)有序列表，原文很明顯強(qiáng)調(diào)了小張晚上回家之后做事的先后順序（最后一項(xiàng)還給出了具體時(shí)間）。

在技術(shù)型文檔中，合理地運(yùn)用列表這種方式去呈現(xiàn)內(nèi)容可以給人一種“邏輯嚴(yán)謹(jǐn)、思路清晰”的感覺，讓讀者更相信你講的內(nèi)容。

在使用列表時(shí)，我們應(yīng)該確保列表中各項(xiàng)內(nèi)容結(jié)構(gòu)一致，即：要么都是名詞，要么都是短語，要么都是句子。這個(gè)原則既能保證你使用列表的初衷（邏輯嚴(yán)謹(jǐn)、思路清晰），也能讓讀者讀起來更舒服。下面是一個(gè)錯(cuò)誤使用列表的示范：

影響系統(tǒng)檢測準(zhǔn)確性的因素有：

• 模型；

• 產(chǎn)品開通過程中，工程師對算法參數(shù)校準(zhǔn)程度；

• 應(yīng)用現(xiàn)場是否有燈光照明。

上面列表一共包含3項(xiàng)，每項(xiàng)的內(nèi)容結(jié)構(gòu)各不相同，第一項(xiàng)是一個(gè)名詞，第二項(xiàng)是一個(gè)句子，第三項(xiàng)是一個(gè)短語。我們將結(jié)構(gòu)統(tǒng)一后，可以調(diào)整為下面這樣：

影響系統(tǒng)檢測準(zhǔn)確性的因素有：

• 模型的復(fù)雜性；

• 部署時(shí)對算法參數(shù)校準(zhǔn)的程度；

• 應(yīng)用現(xiàn)場是否有燈光照明。

上面是將列表中各項(xiàng)內(nèi)容修改為短語，我們還可以換另外一種方式：

影響系統(tǒng)檢測準(zhǔn)確性的因素有：

• 模型類型

• 校準(zhǔn)程度

• 環(huán)境亮度

上面是將列表中各項(xiàng)內(nèi)容修改為名詞，由于是名詞，每項(xiàng)結(jié)尾處不使用任何標(biāo)點(diǎn)符號(hào)（參見前面專門講標(biāo)點(diǎn)符號(hào)的章節(jié)）。下面是對列表運(yùn)用的總結(jié)：

1. 列表一般用于枚舉、過程描述、要點(diǎn)歸納等場合；

2. 需要強(qiáng)調(diào)順序的時(shí)候應(yīng)該使用有序列表，其余視情況而定；

3. 列表中各項(xiàng)內(nèi)容結(jié)構(gòu)應(yīng)保持一致，都是名詞、短語或者句子；

4. 每個(gè)列表前面盡量添加一個(gè)明確的“引入說明”，以冒號(hào)結(jié)束。

使用表格

表格其實(shí)跟面向?qū)ο笥幸欢?lián)系，大部分時(shí)候表格中的一行相當(dāng)于一個(gè)對象，表格中的列相當(dāng)于對象的屬性（字段），表格和面向?qū)ο蠼M織數(shù)據(jù)的方式本質(zhì)上是一致的。技術(shù)型文檔中表格一般用來組織與數(shù)字有關(guān)的內(nèi)容，當(dāng)然也有例外，就像前面章節(jié)中用到的表格，純粹是為了組織文本內(nèi)容。

下面是在技術(shù)型文檔中，使用表格時(shí)可以參考的一些經(jīng)驗(yàn)：

1. 組織數(shù)字相關(guān)內(nèi)容時(shí)，一定要用表格（大部分人可能已經(jīng)有這個(gè)意識(shí)）；

2. 組織結(jié)構(gòu)化類型的文本內(nèi)容時(shí)，盡量用表格；

3. 每個(gè)表格都應(yīng)該配一個(gè)表格標(biāo)題，簡要說明表格內(nèi)容；

4. 文檔中的表格應(yīng)具備一致的樣式和風(fēng)格，比如標(biāo)題字體、背景填充等。

在技術(shù)型文檔中使用表格組織文本內(nèi)容時(shí)，需要控制每個(gè)單元格的文本長度。一般情況下建議單元格中只使用短語，如果必須要用段落，也應(yīng)該控制段落中句子數(shù)量（一般建議不超過2~3句）。下面是錯(cuò)誤使用表格來組織文本內(nèi)容的示范：

表6-1 三種編程語言介紹

上面是以表格的形式來介紹C、C++以及Python三種編程語言，但是在“介紹”那一列中的文本內(nèi)容太長，我們可以換一種表達(dá)方式：

表6-2 C vs C++ vs Python

上面表格一共還是3列，但是現(xiàn)在每列代表一種編程語言，列中的每個(gè)單元格是對該語言的描述，描述內(nèi)容都比較精簡。如果你想繼續(xù)補(bǔ)充內(nèi)容，可以對應(yīng)地增加行即可。

表格的組織方式有多種多樣，行可以變成列、列可以變成行，并沒有嚴(yán)格的限制。我們只需要找一個(gè)適合自己的方式，比如上面這種每列代表一種語言，是因?yàn)樵搱鼍靶枰榻B的編程語言只有三種，如果數(shù)量再多點(diǎn)（或者數(shù)量不確定，后期會(huì)繼續(xù)增加），那么表格寬度就不太夠、這種組織方式就不再合適。

人類在發(fā)明文字媒介之前，用的是圖形符號(hào)。圖像（或圖形、圖片）是所有內(nèi)容表達(dá)方式中最直觀的一種，同時(shí)也能提升讀者的閱讀興趣。有人專門做過研究：在文檔中增加圖像能提升讀者對文檔的喜愛程度，不管這個(gè)圖像跟文檔內(nèi)容本身是否有關(guān)系（https://reurl.cc/RjkrK6）。

也就是說，哪怕在文檔中插入無關(guān)緊要的圖像，讀者也更愿意去嘗試閱讀文檔中其他的內(nèi)容。我們平時(shí)看別人演示PPT時(shí)，如果發(fā)現(xiàn)整頁都是文字描述，大概率就不會(huì)有認(rèn)真去聽的欲望。下面是一段對雙向鏈表的文字描述：

雙向鏈表也叫雙鏈表，是鏈表的一種。它的每個(gè)數(shù)據(jù)節(jié)點(diǎn)中都有兩個(gè)指針，分別指向直接后繼節(jié)點(diǎn)和直接前驅(qū)節(jié)點(diǎn)。所以，從雙向鏈表中的任意一個(gè)節(jié)點(diǎn)開始，我們都可以很方便地訪問它的前驅(qū)節(jié)點(diǎn)和后繼節(jié)點(diǎn)。在應(yīng)用雙向鏈表時(shí)，我們一般構(gòu)造雙向循環(huán)鏈表，鏈表首尾相連。

上面這段描述雙向鏈表的文字本身已經(jīng)非常清晰，對數(shù)據(jù)結(jié)構(gòu)有一定基礎(chǔ)的人看完文字基本就能理解雙向鏈表的結(jié)構(gòu)和應(yīng)用場合（基于它的特點(diǎn)）。但是，如果是一個(gè)零基礎(chǔ)的小白來看這段話，可能效果就不會(huì)太好（尤其如果這段話是作為PPT中的內(nèi)容，大概不會(huì)再有更多的內(nèi)容補(bǔ)充）。如果我們在這段話后面增加一個(gè)插圖，來直觀告訴讀者雙向鏈表長什么樣：

雙向鏈表也叫雙鏈表，是鏈表的一種。它的每個(gè)數(shù)據(jù)節(jié)點(diǎn)中都有兩個(gè)指針，分別指向直接后繼節(jié)點(diǎn)和直接前驅(qū)節(jié)點(diǎn)。所以，從雙向鏈表中的任意一個(gè)節(jié)點(diǎn)開始，我們都可以很方便地訪問它的前驅(qū)節(jié)點(diǎn)和后繼節(jié)點(diǎn)。在應(yīng)用雙向鏈表時(shí)，我們一般構(gòu)造雙向循環(huán)鏈表，鏈表首尾相連。下圖是雙向鏈表結(jié)構(gòu)示意圖：

圖1 雙向鏈表結(jié)構(gòu)

上面的文本配合圖片，能讓讀者更加直觀的理解雙向鏈表的結(jié)構(gòu)特點(diǎn)。當(dāng)文檔中的文本和圖片同時(shí)出現(xiàn)時(shí)，讀者大概率會(huì)先看圖片，然后再結(jié)合文字去理解，加快文檔閱讀速度。

可抽象也可具體

技術(shù)型文檔中的插圖不一定都得是流程圖、架構(gòu)圖、或者結(jié)構(gòu)設(shè)計(jì)圖這種非常具體的技術(shù)相關(guān)圖片，還可以是抽象的、能形象表達(dá)文檔主題的圖片。下面是在技術(shù)型文檔中使用卡通和漫畫圖片的示例：

示例1：

Gitlab中有Label和Tag兩個(gè)概念。

為了便于區(qū)分，這里將Label翻譯成“標(biāo)簽”，將Tag翻譯成“標(biāo)記”（在有些地方這兩個(gè)單詞翻譯并沒有嚴(yán)格的差異）。Gitlab中標(biāo)簽的作用是為了分類、快速地檢索和過濾，用戶能通過標(biāo)簽來直觀的管理Issues，比如to-do、bug等等。

標(biāo)記的主要作用是為了歸檔，給Commit取一個(gè)形象的別名，后期快速定位和查找。GitLab中創(chuàng)建標(biāo)記可以理解為“做記號(hào)”，建立索引。一般推薦為標(biāo)記定義一個(gè)有意義的名稱，比如以版本號(hào)為名，當(dāng)我們要發(fā)布1.0版本，對應(yīng)的標(biāo)記名稱可以是“v1.0”，如果我們要發(fā)布2.0預(yù)覽版，那么對應(yīng)的標(biāo)記名稱可以是“2.0-pre”。

示例2：

源碼版本控制系統(tǒng)（Source Code Version Control System）主要負(fù)責(zé)對源代碼版本進(jìn)行管理，涉及到代碼提交、撤銷、比對、分支管理、代碼合并等功能。源碼管理是軟件開發(fā)過程中非常重要的一個(gè)環(huán)節(jié)，它能有效保證軟件代碼質(zhì)量。

圖1 團(tuán)隊(duì)協(xié)作

源碼管理并不是軟件開發(fā)周期的全部，整個(gè)軟件開發(fā)周期涉及到多個(gè)流程、多個(gè)團(tuán)隊(duì)（多人）協(xié)作完成，包括立項(xiàng)/結(jié)項(xiàng)、進(jìn)度/任務(wù)管理、需求/設(shè)計(jì)、bug管理、測試、集成上線等環(huán)節(jié)。

突出圖中重點(diǎn)

當(dāng)我們想為文檔添加圖片時(shí)，單張圖片包含的內(nèi)容不宜太過復(fù)雜，圖片應(yīng)該能準(zhǔn)確地表達(dá)意思。如果一張圖太過復(fù)雜、或者包含了一些可能引起歧義的部分，我們可以嘗試以下兩種改進(jìn)方式：

1. 將復(fù)雜的圖拆開，一張圖對應(yīng)一個(gè)局部細(xì)節(jié)；

2. 在圖片中將重點(diǎn)區(qū)域標(biāo)記出來，讓讀者可以一眼就發(fā)現(xiàn)重點(diǎn)。

在技術(shù)型文檔中插入復(fù)雜的系統(tǒng)架構(gòu)圖很常見，這種時(shí)候建議遵循“先宏觀，再具體”的原則，循序漸進(jìn)。我們不要一上來就放一張大圖，還想將所有的細(xì)節(jié)都包含進(jìn)去，這種想法不太現(xiàn)實(shí)，這不僅對你畫圖的技能要求很高，讀者看完也容易一臉懵。下面這張圖太過復(fù)雜：

整個(gè)視頻分析系統(tǒng)由3大服務(wù)組成，分別是Intelligent Video Analytics、Front Video Service以及Distribute Load Balance，這3大服務(wù)一共包含15個(gè)子模塊。下面是視頻分析系統(tǒng)結(jié)構(gòu)：

圖1 視頻分析系統(tǒng)結(jié)構(gòu)

上面這個(gè)例子中插入的這張圖既想描述3大服務(wù)之間的交互關(guān)系、又想描述各個(gè)服務(wù)內(nèi)部子模塊之間的交互關(guān)系（上面只是示意圖，實(shí)際情況可能比這個(gè)更復(fù)雜）。文檔讀者碰到這種情況可能會(huì)產(chǎn)生兩個(gè)感覺：一是圖太復(fù)雜了，很難看懂，有些地方迫于空間原因字號(hào)還小；二是我需要重點(diǎn)關(guān)注的點(diǎn)在哪里？如果遵循前面提到的“先宏觀，再具體”的原則，上面這個(gè)例子可以調(diào)整為：

整個(gè)視頻分析系統(tǒng)由3大服務(wù)組成，分別是Intelligent Video Analytics、Front Video Service以及Distribute Load Balance。下面是視頻分析系統(tǒng)中各服務(wù)之間的關(guān)系：

圖1 視頻分析系統(tǒng)服務(wù)交互

其中，Intelligent Video Analytics服務(wù)主要負(fù)責(zé)對視頻解碼、推理以及行為分析等結(jié)構(gòu)化操作。該服務(wù)內(nèi)部一共包含9個(gè)子模塊，模塊之間的關(guān)系見下圖：

圖2 Intelligent Video Analytics服務(wù)子模塊交互

Front Video Service服務(wù)主要負(fù)責(zé)視頻接入、分發(fā)、配置管理等功能。該服務(wù)內(nèi)部一共包含3個(gè)子模塊……

另外一種情況，插入的圖片中包含了不相干內(nèi)容，文檔作者又沒有給出醒目的標(biāo)記，讀者看完不清楚關(guān)注重點(diǎn)在哪里。下面是錯(cuò)誤的示例：

GitLab中的Release功能主要用來對倉庫中的代碼以及其他一些相關(guān)資料文件進(jìn)行歸檔，通常用于版本發(fā)布。當(dāng)有新版本發(fā)布時(shí)，用戶可以基于對應(yīng)的Commit創(chuàng)建一個(gè)Tag標(biāo)記，給它一個(gè)合理的名字，比如“v1.0-pre”（代表發(fā)布1.0預(yù)覽版），然后再基于該Tag發(fā)布版本。

后期，其他人可以通過Release菜單快速瀏覽、檢索項(xiàng)目版本發(fā)布記錄以及對應(yīng)時(shí)間點(diǎn)的相關(guān)代碼和資料。用戶可以在GitLab主界面的左側(cè)菜單中找到Release功能入口：

圖1 Gitlab中Release菜單

上面圖片在介紹Release功能時(shí)給出的圖片中包含的菜單項(xiàng)太多，為了讓讀者更直觀看懂圖片關(guān)注點(diǎn)，可以將圖片調(diào)整如下（左右兩種都可以）：

GitLab中的Release功能主要用來對倉庫中的代碼以及其他一些相關(guān)資料文件進(jìn)行歸檔，通常用于版本發(fā)布。當(dāng)有新版本發(fā)布時(shí)，用戶可以基于對應(yīng)的Commit創(chuàng)建一個(gè)Tag標(biāo)記，給它一個(gè)合理的名字，比如“v1.0-pre”（代表發(fā)布1.0預(yù)覽版），然后再基于該Tag發(fā)布版本。

后期，其他人可以通過Release菜單快速瀏覽、檢索項(xiàng)目版本發(fā)布記錄以及對應(yīng)時(shí)間點(diǎn)的相關(guān)代碼和資料。用戶可以在Gitlab主界面的左側(cè)菜單中找到Release功能入口：

圖1 Gitlab中Release菜單

有準(zhǔn)確的圖標(biāo)題

圖片是為了讀者能夠更直觀地理解文檔內(nèi)容，但是圖片畢竟不是文字，不同的人對同一張圖片理解可能存在差異，尤其對于那種不包含任何文字的圖片。因此，在文檔中插入任何圖片時(shí)，我們應(yīng)該為它定義一個(gè)合適、貼切的標(biāo)題。圖標(biāo)題一般是一個(gè)名詞或者短語，作用跟前面講到的表格標(biāo)題一樣，協(xié)助讀者理解圖片所要表達(dá)的含義。

文檔的樣式和風(fēng)格其實(shí)跟我們寫代碼一樣，寫代碼要遵守統(tǒng)一的代碼風(fēng)格（變量命名、換行規(guī)則等等），寫文檔也應(yīng)該遵守統(tǒng)一的文檔風(fēng)格。公司或者組織一般都有自己的文檔風(fēng)格規(guī)范，規(guī)范會(huì)定義好正文/標(biāo)題字體字號(hào)、頁眉頁腳、頁邊距、行間距、段前段后間距等等，按照規(guī)范寫出來的文檔風(fēng)格基本就能保持一致。

對于沒有規(guī)范可用的場合，文檔作者可以根據(jù)自己的偏好執(zhí)行即可，保證整篇文檔的內(nèi)容遵守相同的風(fēng)格，比如文檔開頭和文檔結(jié)尾的段落間距、列表樣式、對齊方式都應(yīng)該保持一致。本篇文檔的主要規(guī)范定義如下：

1. 頁邊距上下左右2cm；

2. 標(biāo)題18號(hào)華文仿宋，正文12號(hào)宋體，正文中表格/圖標(biāo)題12號(hào)華文仿宋；

3. 段前/段后間距0.5，段落行間距1.5倍，段落首行對齊不空格；

4. 表格、圖片居中對齊，圖標(biāo)題在圖片下方、表格標(biāo)題在表格上方。

還有另外一些比較重要的樣式定義，比如列表樣式（本篇文檔中每個(gè)列表外面套了一個(gè)表格，表格無左右邊框），還比如本篇文檔涉及到了很多舉例和示范，所有的舉例示范都在表格中，并且表格有自己的樣式（字體字號(hào)、背景顏色等等）。

把握好整體文檔結(jié)構(gòu)是一件非常困難的事情，這個(gè)其實(shí)跟前面講到的文檔內(nèi)容本身沒什么關(guān)系。文檔作者在動(dòng)筆之前需要有一個(gè)宏觀的構(gòu)思，需要在腦子里先將文檔大綱梳理一遍，一級(jí)標(biāo)題可以是什么、二級(jí)標(biāo)題又可以是什么，然后考慮將合適的內(nèi)容放到對應(yīng)的章節(jié)中去。

優(yōu)秀的作者在正式動(dòng)手之前，可能已經(jīng)有了很長一段時(shí)間的思考準(zhǔn)備，尤其對于那種非常復(fù)雜的文檔。但是這種方式對一些人來講可能不太現(xiàn)實(shí)，難度太大。那么這時(shí)候就只能考慮另外一種方式，動(dòng)手之前先在白紙上打草稿，列出來文檔大綱，然后不斷修改和調(diào)整，直到滿意為止。

其實(shí)不管上面哪種方式，文檔結(jié)構(gòu)考驗(yàn)的是作者組織內(nèi)容的思維能力。對于一些需求、設(shè)計(jì)類型的“主流”技術(shù)型文檔，考驗(yàn)的是作者對軟件需求、系統(tǒng)架構(gòu)的理解深度，該寫什么不該寫什么，寫到什么程度，這些都需要作者考慮清楚，這類型的文檔一般有標(biāo)準(zhǔn)的模板可以參考，大家平時(shí)寫得/見得也比較多。

對于另外一些“非主流”類型的技術(shù)型文檔，比如對某個(gè)線上問題的分析報(bào)告、技術(shù)/原型調(diào)研類文檔，這些文檔一般規(guī)模比較小、也沒什么參考標(biāo)準(zhǔn)，全靠作者自己去組織。

下面就以“對某個(gè)用戶需求做技術(shù)性反饋”為例，拋磚引玉，簡單描述一下技術(shù)型文檔結(jié)構(gòu)應(yīng)該如何去組織：

場景說明：

視頻分析系統(tǒng)中，客戶要求在事件錄像文件中對涉事車輛目標(biāo)（或區(qū)域）進(jìn)行高亮標(biāo)框顯示，視頻錄像在播放時(shí)會(huì)有一個(gè)醒目的多邊形提醒用戶具體事件發(fā)生位置?？蛻舳恍┘夹g(shù)相關(guān)知識(shí)，要求公司技術(shù)研發(fā)團(tuán)隊(duì)針對該需求給出合理的需求反饋，如果需求可實(shí)現(xiàn)，評(píng)估工作難度；如果需求不可實(shí)現(xiàn)，說明具體原因。

根據(jù)上面場景說明，該需求并非硬性要求。甲方提出了一個(gè)想法，并且非常貼心地考慮到了乙方是否具備條件實(shí)現(xiàn)，希望給出一個(gè)實(shí)質(zhì)性的答復(fù)。公司技術(shù)團(tuán)隊(duì)在寫反饋說明文檔之前，應(yīng)該考慮以下兩個(gè)問題：

1. 如果正常響應(yīng)該需求，具體的方案是什么、難點(diǎn)/風(fēng)險(xiǎn)點(diǎn)各是什么；

2. 如果不能正常響應(yīng)該需求，具體原因是什么，是否有可替代方案、替代方案是什么。

也就是說，不管最終團(tuán)隊(duì)是否響應(yīng)該需求，我們在文檔中都要有非常實(shí)質(zhì)性的內(nèi)容，不應(yīng)該是空話、套話。下面就以“不響應(yīng)”為例，描述文檔應(yīng)該包含哪些內(nèi)容：

需要注意的是，“響應(yīng)”或者“不響應(yīng)”的決定很多時(shí)候不在技術(shù)團(tuán)隊(duì)或者寫這個(gè)文檔的人手里。雖然文檔中的內(nèi)容應(yīng)該為最終的結(jié)論服務(wù)，但是總體上不應(yīng)該有偏差。

文檔的目標(biāo)群體是誰？這個(gè)其實(shí)應(yīng)該是寫文檔最開始就需要明確的東西，面對不同的群體，我們文檔的內(nèi)容、結(jié)構(gòu)包括內(nèi)容描述程度都會(huì)不同。盡早確定讀者有助于在構(gòu)思階段就明確文檔內(nèi)容邊界，哪些該寫、哪些不該寫，該寫的又應(yīng)該如何去寫，這些都是編寫文檔的大方向。

作者：周智，前微軟（中國）Windows工程院員工，目前從事于深度學(xué)習(xí)計(jì)算機(jī)視覺相關(guān)工作，交通安防領(lǐng)域的視頻目標(biāo)檢測、跟蹤和行為分析。

成都招聘技術(shù)合伙人20-25K:

https://www.didaproject.com/index.php?c=show&id=104

同時(shí)還招JAVA：

https://www.didaproject.com/index.php?c=show&id=103 

新鮮職位，歡迎推薦