如何寫好一篇技術型文件
周智 2022/1/20
參加工作時間久一點的工程師應該有這樣一個體會：自己平時程式碼寫得再多再好，可一旦要用文件去描述或者表達某一個事情或者問題時，都感覺非常困難，無從下手，不知道自己該寫什麼不該寫什麼；或者費了九牛二虎之力寫出來的東西沒法滿足要求，需要再三去修改調整。這其中的主要原因我歸納有兩點：
- 思維方式固化。大部分人平時程式碼寫得太多，文字型別的表述又寫得太少。而程式碼和文字明顯是兩種不同的思維方式，在程式碼裡陷得太深，不容易跳出來；
- 本身文字表達能力有限。這個跟寫程式碼一樣，有人程式碼質量高、bug少；有人水平低、bug自然就多。
以上兩點其實都可以通過平時多練、多寫、多梳理的方式去彌補，比如週期性的部落格總結和記錄。但是，如果你能刻意系統性地去補充一些關於“技術型寫作”的理論知識，一定能夠事半功倍。這就像我們剛學程式設計時，一頓學、一頓模仿，但是總感覺缺了點什麼，自己再努力發現深度還是不夠。這時候，我們需要做的是看一本高質量的經典書籍，書籍能幫我們梳理知識點、總結各種碰到過的問題，從理論上解答我們心中各種疑惑，將之前的野路子“正規化”。
下面是我根據平時的一些積累，將技術型寫作的理論知識歸納成10個要點：
- 1 搞清楚主謂賓
- 2 不濫用代詞、過渡詞和標點符號
- 3 多用強勢動詞，少用形容詞和副詞
- 4 正確使用術語
- 5 正確使用段落
- 6 適當使用列表和表格
- 7 一圖勝千言
- 8 統一樣式和風格
- 9 把握好整體文件結構
- 10 明確文件的目標群體
1 搞清楚主謂賓
文件主要由段落組成，段落由句子組成，而大部分句子又由“主謂賓”組成（可能有些場合省略了，但是讀者可以通過上下文輕鬆get到）。主謂賓是主幹骨架，其他內容可以看作是句子的修飾，主幹骨架是決定句子是否垮掉的主要原因。現在很多人可能已經忘記了句子的基本構成，畢竟以漢語為母語的人，大概率是不太會關心這些“細節”，就像說英語的國家可能不太關心am is are一樣，你說哪個人家都理解。但是，文件中的一句話讀起來是否彆扭，大多數時候是由句子構成決定的。在不考慮文件上下文的情況下，如果一個句子能包含正確的主語、謂語和賓語（可選），那麼它讀起來至少是很順口的。下面舉一個明顯搞不清主謂賓的例子：
<×>
傳統影像處理演算法，通過計算煙火顏色特徵，極易受煙火周圍環境相近顏色干擾而造成誤檢。
儘管你能讀懂作者想要表達的意思，但是這句話讀起來還是太彆扭。“傳統影像處理演算法”應該算是主語，後面的“通過…”這句不完整，“極易受…干擾”這句還可以，“…造成誤檢”算是謂語賓語，但是這裡用錯了動詞，為什麼是“演算法造成誤檢”，難道不是“周圍環境相近顏色干擾造成誤檢”嗎？
這句話的主幹內容是：演算法極易受…影響而…。正確的表述應該類似下面這樣：
<√>
因為傳統影像處理演算法通過計算煙火顏色特徵去識別煙火，所以它極易受煙火周圍環境相近顏色干擾而出現誤檢。
我們用過渡詞（因為...所以…）將原來的句子拆成了前後兩個部分，前面部分的主語是“傳統影像處理演算法”，謂賓是“識別煙火”；後半部分的主語是“它”，謂賓是“出現誤檢”。經過調整後，前後兩個部分的主語是同一個：傳統影像處理演算法。下面再直觀看一下修改之後的句子主幹骨架：
<因為><傳統影像處理演算法>通過計算煙火顏色特徵去<識別煙火>， <所以><它>極易受煙火周圍環境相近顏色干擾而<出現誤檢>。
如果你覺得用“因為…所以…”不太好，那麼可以再換一種表述：
<√>
傳統影像處理演算法通過計算煙火顏色特徵去識別煙火，煙火周圍環境相近顏色的干擾極易造成誤檢。
第一句還是跟之前一樣，主語是“傳統影像處理演算法”，第二句主語變成了“干擾”，謂賓是“造成誤檢”。下面我們直觀地看一下修改之後的句子主幹骨架：
<傳統影像處理演算法>通過計算煙火顏色特徵去<識別煙火>， 煙火周圍環境相近顏色的<干擾>極易<造成誤檢>。
最後再舉一個錯誤的例子：
<×>
由於誤報率與漏報率很高，因此不管是否有真實事件發生都會去留意，也會有規定的日程定點巡查視訊任務。
上面這個句子的作者完全沒搞懂誰是主語，誰是謂語。感興趣的童鞋可以試著修改一下，改成你認為正確的表述。
2 不濫用代詞、過渡詞和標點符號
2.1 不濫用代詞和過渡詞
中文文件中的代詞主要有：你我他她它、其、前者、後者、這樣、那樣、如此等等，過渡詞主要有：因為/所以、不但/而且、首先/然後等等。下面這張表格列舉了一些常見的代詞和過渡詞及其常用場合：
表2-1 代詞和過渡詞舉例
| 序號 | 型別 | 名稱 | 常用場合舉例 |
|---|---|---|---|
| 1 | 代詞 | 其 | C語言中引入了“指標”的概念，其作用是為了能夠提升記憶體訪問速度。 |
| 2 | 代詞 | 後者 | C語言發明於1970年代，C++語言發明於1980年代，後者主要引入了物件導向思想。 |
| 3 | 代詞 | 此 | 指標能夠提升程式訪問記憶體的速度，但此特點仍存在一些缺陷。 |
| 4 | 代詞 | 它 | C語言的一大特性是指標，這就像C++語言和它的物件導向思想一樣。 |
| 5 | 過渡詞 | 因為/所以 | 因為神經網路可以自動提取資料特徵，所以基於神經網路的深度學習技術中不再有傳統意義上的“特徵工程”這一概念。 |
| 6 | 過渡詞 | 首先/然後 | 首先我們要保證有足夠多的訓練資料，然後我們再選擇一個適合該問題的神經網路模型。 |
代詞和過渡詞就像標點符號一樣，容易被濫用。代詞濫用主要體現在作者在使用它們的時候並沒有搞清楚它們代表的究竟是誰，是前一句的主語、還是前一句的賓語或者乾脆是前一整句話？過渡詞濫用主要體現在作者在使用它們的時候並沒有搞清楚前後兩句話的邏輯關係，是遞進還是轉折或者是因果？（過渡詞濫用頻率要低很多，畢竟搞清楚前後句子邏輯的難度要小）接下來舉幾個濫用代詞和過渡詞的例子：
<×>
C++語言發明於1980年代，它支援“指標”和“物件導向（Object-Oriented）”兩個特性，其價值在計算機程式語言歷史上數一數二。
上面這個句子中出現了兩個代詞“它”和“其”，拋開句子內容本身對錯不論，第二個代詞指向的物件其實並不明確，“其”指的是“指標”、“物件導向”還是“C++語言”？或者是指“C++語言同時支援...兩個特性”這個陳述？像這種有歧義的場合，我們應該少用代詞，儘量用具體的主語去代替：
<√>
C++語言發明於1980年代，它支援“指標”和“物件導向（Object-Oriented）”兩個特性，C++的價值在計算機程式語言歷史上數一數二。
如果你一定要用代詞，那麼調整一下可能更好：
<√>
C++語言發明於1980年代，它同時支援“指標”和“物件導向（Object-Oriented）”兩個特性，這個價值在計算機程式語言歷史上數一數二。
再讀一讀，你是不是沒有感覺到歧義了？我們在“支援”前面增加了一個“同時”，然後將代詞換成了“這個”，現在這個代詞指的是“C++語言同時支援...兩個特性”這個陳述，修改後整個句子的意思更明確。
我們再來看另外一個濫用代詞的例子：
<×>
該模組主要負責對視訊進行解碼，輸出單張YUV格式的圖片，並對輸出的圖片進行壓縮和裁剪，前者基於Resize方法來完成，後者基於Crop()方法完成。
對於大部分人來講，上面這段沒什麼問題。代詞“前者”指的是壓縮、“後者”指的是裁剪，原因很簡單，因為單詞Resize對應的是壓縮、單詞Crop對應的是裁剪。但是這段話如果拿給沒有任何知識背景的人去讀（大概率可能是找不到這種人），恐怕會存在歧義，主要原因是代詞前面提到了很多東西，“前者”和“後者”指向不明確，到底是指“解碼”、“輸出單張圖片”還是後面的“壓縮”和“裁剪”？下面這樣調整後，整段話的意思更加明確：
<√>
該模組主要負責對視訊進行解碼，輸出單張YUV格式的圖片，並對輸出的圖片進行壓縮和裁剪，壓縮基於Resize方法來完成，裁剪基於Crop()方法完成。
我們去掉了代詞，直接用具體的主語來代替，句子意思非常明確。如果你一定要使用代詞，那麼也可以這樣調整：
<√>
該模組主要負責對視訊進行解碼，輸出單張YUV格式的圖片。同時，它還對輸出的圖片進行壓縮和裁剪，前者基於Resize()方法完成，後者基於Crop()方法完成。
上面這段話還是使用了代詞“前者”/“後者”，但是我們修改了標點符號，並且增加了一個過渡詞“同時...”，這樣做的目的是讓讀者知道雖然整段話說的是同一個東西，但是前後的句子已經分開了，為我們後面使用代詞做好準備。
好的，現在我們來總結一下在技術型文件編寫過程中使用代詞時的一些有價值經驗：
- 代詞可以指它前面出現過的名詞、短語甚至整個句子，但是一定是前面出現過的；
- 代詞的位置和它要指向的目標最好不要隔得太遠，1~3句話之內，超過就不要用了；
- 代詞的作用是減少小範圍內某些詞彙或句子重複出現的頻率，要用到恰到好處；
- 代詞前面出現的混淆目標如果太多，一定要重新調整句子，確保代詞指向無歧義。
2.2 不濫用標點符號
接下來我們再看另一個，標點符號的濫用要普遍很多，其主要原因是：標點符號的使用並沒有非常明確的對錯之分。至少對大部分人而言，使用句號還是逗號其實並沒有什麼嚴格的評判標準，只要不出現“一逗到底”的極端情況，其餘大概率都OK。下面這張表格是我根據以往經驗，總結出來的應用於技術型寫作時中文標點符號使用規則：
表2-2 常用標點符號
| 序號 | 符號 | 寫法 | 使用場合 |
|---|---|---|---|
| 1 | 逗號 | ， | 前後兩句話關聯性比較大，閱讀時停頓時間短。 |
| 2 | 句號 | 。 | 前後兩句話關聯性比較小，閱讀時停頓時間稍長。 |
| 3 | 分號 | ； | 前後兩句話地位相對平等，句子的內容和格式基本保持一致。比如列表中，如果每項是一個句子或者短語，那麼第1至第N-1項結尾使用分號，第N項結尾使用句號。 |
| 4 | 冒號 | ： | 技術型文件中，冒號一般用在需要引入重要內容的場合。比如當你需要插入一張表格或者一張圖片時，需要提前做一個提醒（下表列舉了常見的代詞和過渡詞：），提醒結束時補充一個冒號。 |
| 5 | 括號 | （） 【】 | （）一般用於解釋性的場合，負責對名詞或者句子的補充解釋。 【】用得比較少，我一般用於需要增加醒目標記的名詞或短語中。 |
| 6 | 頓號 | 、 | 一般可以用在列舉名詞或者短語的場合。 |
| 7 | 問號 | ？ | 不用多解釋。 |
| 8 | 引號 | “” ‘’ | 一般用於標記特殊名詞、專用名詞、短語，或需要重點突出的名詞或短語。 |
| 9 | 分隔號 | / | 一般用於成對出現的名詞（舉例：因為/所以、首先/然後等等都是過渡詞），或者根據文件上下文來判斷地位差不多的相近詞（舉例：演算法的好壞直接影響最終報表中誤報/誤報率那一欄）。 |
| 10 | 破折號 | —— | 用得不多。 |
| 11 | 省略號 | ... | 不用多解釋。 |
| 12 | 感嘆號 | ！ | 技術型文件不是寫小說，用得不多。 |
| 13 | 書名號 | 《》 <> | 不用多解釋。 |
上面這張表格基本涵蓋了常用的中文標點符號，其中有一小部分在技術型文件中不太常見，比如感嘆號、破折號，這些符號多多少少帶有某種感情色彩，不太適合用於技術型文件編寫。前面已經簡單概括了一下各個符號的使用場合，下面挑幾個容易出錯的再一一詳細說明：
<×>
C++語言發明於1980年代，它衍生自C語言，主要引入了“物件導向（Object-Oriented）”思想，物件導向思想強調對資料的封裝和對功能的複用，此特性有利於開發者對程式碼的維護和擴充套件，目前，大部分計算機程式語言已經支援了物件導向特性。
上面這段話屬於典型的“一逗到底”的例子。作者從C++語言說到了物件導向思想，最後總結大部分計算機程式語言都支援物件導向。我們如果將整段話拆開來看，其實它想表述的是3個內容，每個內容之間最好使用句號，停頓時間稍長一些。我們調整之後的效果是：
<√>
C++語言發明於1980年代，它衍生自C語言，主要引入了“物件導向（Object-Oriented）”思想。物件導向思想強調對資料的封裝和對功能的複用，此特性有利於開發者對程式碼的維護和擴充套件。目前，大部分計算機程式語言已經支援了物件導向特性。
接下來我們再看看分號的使用。根據我個人經驗，分號常用在列表場合，下面舉一個例子說明：
下面是“將大象裝入冰箱”的具體步驟：
- 開啟冰箱門；
- 將大象裝進冰箱；
- 關上冰箱門。
上面是一個有序列表，列表中的各項內容是一個短語。當列表中各項內容是短語或者句子的時候，除最後一項之外其餘專案結尾一般都使用分號（注意，同一個列表中各項的格式最好都保持一致，要麼都是短語，要麼都是單個的名詞，這個後面專門講列表的時候會提到）。如果列表中各項內容只是一個名詞時，那麼結尾就可以不用標點符號：
下面是“可以被裝進冰箱”的動物：
- 狗子
- 大象
- 猴子
- 鸚鵡
上面是一個無序列表，列表中的各項內容是一個名詞，這時候名詞結尾處不需要新增任何標點符號。
我們最後再來看一下小括號的使用場合。在技術型文件中，小括號主要用於對前面的名詞、短語或者句子進行補充說明，比如當文件中出現縮寫詞彙時，我們會在它的後面增加一個小括號，在括號裡面註明該縮寫詞彙的全稱。下面舉一個使用小括號對縮寫詞彙解釋說明的例子：
API（Application Program Interface）是系統對外提供的訪問介面，使用者可以按照API文件中的介面定義去訪問系統中的資料，並與它做一些互動。
上面這段話主要講API是什麼、可以幹什麼。它是Application Program Interface三個單詞的簡稱，為了讓讀者更清楚該術語的定義，作者可以選擇在第一個“API”出現的位置增加一個小括號，並將術語全稱補充進來，之後的整個文件無需再重複該操作（後面會單獨提到術語全稱和簡稱的運用規則）。
除了能對縮寫詞彙進行解釋說明之外，小括號還可以用於對前面整個句子進行補充說明，再看下面這個例子：
它是Application Program Interface三個單詞的簡稱，為了讓讀者更清楚該術語的定義，作者可以選擇在第一個“API”出現的位置增加一個小括號，並將術語全稱補充進來，之後的整個文件無需再重複該操作（後面會單獨提到術語全稱和簡稱的運用規則）。
上面這段話其實前面已經出現過，最後小括號裡面的內容主要是為了對它前面一句話進行補充。如果補充性說明內容太長，比如要好幾句話才能起到補充的作用，那麼這個時候我們就不應該再使用小括號了，可以考慮調整句子結構，然後將補充性的內容當作段落主體的一部分。
關於代詞、過渡詞以及標點符號濫用的內容就講到這裡，其中有一些內容是我個人的寫作喜好，其實並沒有非常明確的對錯之分，比如前面講到列表中分號的使用，很多人這時候可能選擇使用句號。大家可以根據自己的判斷去處理這種模稜兩可的場景，當然一些比較確定的規則，比如當列表項只有名詞的時候，列表項結尾不要使用任何標點符號，這一點還是比較確定的。
3 多用強勢動詞，少用形容詞和副詞
3.1 強勢動詞和主動語句
很多人可能第一次聽到“強勢動詞”這個說法，陌生還難以理解。如果將它翻譯成英文，對應的單詞應該是“Strong Verbs”，意思是強有力的動詞，你可以理解為：聽起來動作幅度大、衝擊力強的那一類動詞。打個比方，假如“走”是弱勢動詞，那麼“跳”就是強勢動詞；假如拿刀“切”是弱勢動詞，那麼拿刀“砍”就是強勢動詞。下面這張表格列舉了一些強勢/弱勢動詞的例子：
表3-1 強勢/弱勢動詞對比
| 序號 | 弱勢動詞 | （可考慮）強勢動詞 |
|---|---|---|
| 1 | 走過去 | 跳過去 |
| 2 | 切肉 | 砍肉 |
| 3 | 出現異常 | 丟擲異常 |
| 4 | 程式退出 | 程式崩潰 |
| 5 | 記憶體增長 | 記憶體洩漏 |
| 6 | 找不到日誌檔案 | 日誌檔案丟失 |
| 7 | 客戶提出質疑 | 客戶投訴 |
| 8 | 任務未完成 | 任務延期 |
| 9 | 角色許可權是由管理員設定的 | 管理員控制角色許可權 |
| 10 | 系統無法正常使用API返回的結果 | 系統無法正常解析API返回的結果 |
上面列出了10對強勢/弱勢動詞，我們觀察可以發現：弱勢動詞一般無法正確表達問題/事情的真實情況。在技術型文件編寫過程中，雖然我們不能借助詞彙使用、句子構成以及標點符號等手段去傳遞感情傾向，但是也不能掩蓋真實準確的內容表達。
在提到強勢動詞時，我們還要注意“主動語句”和“被動語句”的區別。在技術型文件編寫過程中，應該儘量少使用被動語句。下面這張表格列舉了一些主動/被動語句的例子：
表3-2 主動/被動語句對比
| 序號 | 被動語句 | （可考慮）主動語句 |
|---|---|---|
| 1 | 角色許可權是由管理員控制的 | 管理員控制角色許可權 |
| 2 | API結果無法被系統正常解析 | 系統無法正常解析API結果 |
| 3 | 影像特徵是通過CNN逐步降維的方式提取的 | CNN通過逐步降維的方式提取影像特徵 |
| 4 | 這種檢測效果無法被客戶接受 | 客戶無法接受這種檢測效果 |
| 5 | 經過研發排查發現，這個現象是正常的（*） | 經過研發排查發現，這個屬於正常現象 |
上面表中第5項（帶*號）嚴格來講不算被動語句，但是在技術型寫作過程中，我們應該避免使用“...是...的。”這種句式，該句式太過口語化。儘量少用被動語句的原因有以下三個：
- 讀起來麻煩。讀者讀到被動語句時，需要先在腦子裡將其轉換一下再去理解；
- 難以理解。讀者有時候很難分清被動語句中的真實主語（甚至可能省略了主語）；
- 字數多。被動語句一般更長、字數更多。
那麼被動語句是不是完全不讓用了呢？當然不是。仔細的讀者可能已經觀察到了前面在舉例的時候我們有這樣一段話：
C++語言<發明於>1980年代，它支援“指標”和“物件導向（Object-Oriented）”兩個特性，C++的價值在計算機程式語言歷史上數一數二。
上面第一句中的“...於”其實就是被動語句，像“C++語言發明於...”、“該文件編輯於...”這些都算被動語句，由於賓語（這裡是C++語言）更重要，所以預設省略了真實主語（某某發明C++語言，可是某某在這裡不太重要）。這類句子結構有一個特點就是：賓語比真實主語重要，所以放到句子的開頭位置。
3.2 少用形容詞和副詞
技術型文件講究的是一個“準”字，它不像小說、散文之類的文學作品帶有很強的感情色彩，也不同於網路部落格可以摻雜一些非正式詞彙，更不能跟Marketing Speech（營銷話語）一樣常常誇大其詞。為了做好前面說的“準”，技術型文件應該儘量少用形容詞和副詞，因為這些詞語大部分都屬於“主觀”表達。下面舉幾個使用形容詞和副詞的例子：
<×>
為了保證系統執行更高效，他們嘗試儘可能壓縮圖片尺寸，事實證明這個嘗試非常成功。這樣的工作看似簡單，卻蘊含著高技術含量。
上面這段話使用了好幾個副詞和形容詞，比如“儘可能”、“非常”、“高”。如果是技術型文件，這段話建議調整為：
<√>
為了提高系統執行效率，他們將圖片尺寸壓縮到原來的1/3，系統響應速度提升2倍。
我們用具體的數值替換了原來的形容詞和副詞，並且直接刪掉了最後一句話，最後一句話在技術型文件中起不到任何作用。下面這張表格列舉了部分形容詞和副詞使用不恰當的場合：
表3-3 形容詞/副詞使用不恰當舉例
| 序號 | 形容詞/副詞 | （可考慮）調整為 |
|---|---|---|
| 1 | 經過優化，介面響應速度提升明顯 | 經過優化，介面響應速度提升2倍 |
| 2 | 很多人反應現場誤報很多 | 資料統計發現，現場誤報率為11% |
| 3 | 大部分客戶投訴說系統很不好用 | 最近一個月有超過50個客戶投訴說系統不好用 |
| 4 | 升級依賴庫後，該函式執行很快 | 將依賴庫升級到2.3.1版本後，該函式執行時間縮短到100ms以內 |
| 5 | 研發同事很辛苦，每天加班很晚 | 研發同事很辛苦，每天23:00之後才下班 |
最後，我們來總結一下：
- 優先使用方便讀者閱讀理解的動詞和句式（強勢動詞和主動語句）；
- 儘量少用形容詞和副詞，用具體數值代替、或者調整句子表述。
4 正確使用術語
這裡提到的術語分兩種：一種是計算機領域通用的專業術語，像SDK、物件導向、TCP/IP、微服務等等這些名詞，它們基本已經被大眾接受和理解，我們在編寫文件的時候不能隨意再重新去命名、調整或者改變拼寫（將“TCP/IP”寫成“Tcp/ip”）；另外一種是當前文件需要定義的術語，這種術語只有在當前文件上下文中才有效。我們在編寫技術型文件時，通過自己的判斷，如果認為文件讀者缺乏對相關術語（不管是前面哪一種）的理解，我們都應該在文件靠前位置給出對術語的解釋說明，也就是我們平時文件中常見的“名詞解釋”。
表4-1 名詞解釋舉例（*為自定義術語）
| 序號 | 名詞 | 說明 |
|---|---|---|
| 1 | SDK | Software Development Kit，軟體開發包，開發者基於該工具包開發更豐富的高層應用。 |
| 2 | 記憶體洩漏 | 通過new/malloc等方法申請的記憶體在使用完後未被及時釋放，程式執行記憶體佔用越來越高。 |
| 3 | 物件導向 | 強調對資料和功能的封裝，提升程式碼的可複用性、可擴充套件性以及靈活性。 |
| 4 | FVM（*） | Front Video Manager，前端視訊管理服務，負責視訊接入、分發等業務。 |
| 5 | 視訊大資料標籤服務（*） | 對視訊進行結構化處理，生成結構化標籤，並對外提供標籤檢索等功能。 |
有些文件可能篇幅比較短，並不是傳統意義上的需求設計類文件，比如對某個線上問題分析的結果彙報、對某個模型檢測效果的驗證報告、或者研發階段性的工作總結。這些文件由於本身內容就不多，大部分可能直接進入主題，這時候如果還要在文件中專門增加一塊名詞解釋的版塊（並且總共也就一兩個術語），就顯得比較突兀。
另外一種對術語進行解釋說明的方式是用我們前面提到的小括號，我們可以在術語後面增加一個小括號，然後在括號裡新增補充說明。這種方式很便捷，但是隻適合簡單的場景，比如在小括號裡面補充術語的全稱或者簡稱，或者只做簡單的解釋說明。如果對一個術語的解釋內容很長，就不太適合用這個方法，下面舉一個錯誤的例子：
<×>
當視訊離線時，FVM（Front Video Manager，前端視訊管理服務，負責視訊接入、分發等業務。）會產生一條告警記錄，並存入節點資料庫。
上面這個術語解釋內容太長，不太適合使用小括號的方式，這種情況要麼在文件正文中專門對FVM進行解釋，要麼在小括號中只給出FVM的英文全稱即可：
<√>
當視訊離線時，FVM（Front Video Manager）會產生一條告警記錄，並存入節點資料庫。
使用小括號去做術語解釋還需要注意一點的是：只需要在術語第一次出現的時候做一次解釋即可，不需要重複多次。下面舉一個重複的錯誤例子：
<×>
當視訊離線時，FVM（Front Video Manager）會產生一條告警記錄，並存入節點資料庫。之後節點資料庫會將該條告警記錄同步到平臺資料庫，平臺FVM（Front Video Manager）檢測到有新的告警記錄時，會通過訊息中介軟體通知業務系統，業務系統隨後將告警資訊以簡訊（或釘釘）的方式通知到使用者。
上面對術語FVM的解釋重複了兩次，這種做法是錯誤的，第二次我們可以直接去掉。
有些術語存在全稱和簡稱，我們熟悉的SDK全稱是“Software Development Kit”，但是現在基本沒有人再去使用它的全稱。像這種簡稱已經被大眾熟知的術語，我們就不能再標新立異的去用它的全稱。另外一些在文件中自定義的術語，文件作者為了便於閱讀可能也會提供一個簡寫的版本，在這種情況下，文件前後應該保持一致，即：要麼整篇文件都用全稱，要麼都用簡稱，儘量做到一致。下面舉一個全稱簡稱使用不一致的例子：
<×>
IVA（Intelligent Video Analytics，智慧視訊分析）服務主要負責視訊解碼、模型推理、目標跟蹤以及目標行為分析，該服務是整個系統中最複雜的一個模組。智慧視訊分析服務由張三團隊開發完成，一共耗時6個月，人力成本開銷120萬。
上面這段話中，前半部分作者使用“IVA”簡稱（小括號中做了全稱說明），但是在後面一句話中作者又使用了全稱“智慧視訊分析”，這種做法沒有遵循統一原則。不僅同一段落應該保持統一，整篇文件也應該做到統一，術語在文件中第一次出現時是簡稱，那麼整篇文件都應該用簡稱，反之亦然。
最後我們來總結一下，在技術型文件中使用術語時需要注意的一些事項：
- 文件讀者不熟悉的術語（包括通用術語和文件自定義術語）都應該有解釋說明；
- 小括號只適合簡短的術語解釋場合，括號裡的內容不能太長（一兩句短語之內）；
- 任何方式的術語解釋只需要有一次即可（術語第一次出現時），不要解釋多次；
- 術語的全稱和簡稱要保持使用一致，要麼整篇文件都用全稱、要麼都用簡稱；
- 對於計算機領域的通用專業術語，需要沿用主流用法，不要隨意再去調整。
5 正確使用段落
5.1 單一職責
與物件導向程式設計中“類的單一職責原則”一樣，文件中的句子（特指以句號結尾的一句話）、段落也應該遵循“單一職責原則”。前面講標點符號的時候已經提到過，同一段話中前後關聯性不大的兩句話之間用句號，這樣可以保證每句話想要表達的是相對獨立的內容。段落也一樣，一個段落只陳述一個主題，可以保證段落的句子不會太多、內容不會太長，便於讀者閱讀和理解。下面舉一個段落使用錯誤的例子：
<×>
Excel提供一個組織資料的高效方法。我們可以將Excel想象成一個有行和列的二維表格，每一行代表一個獨立的實體，每一列代表該實體的不同屬性。Excel還具備數學功能，比如計算平均值和方差等數學操作。如果你想使用Excel來記錄圖書資訊，那麼每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價格以及出版社等等資訊。
上面這段話的第一句已經明確了段落主題：Excel能高效地組織資料。可是，這段話中間卻穿插了一個不相干的句子，說Excel具備數學功能，能夠做一些數學操作，這句話顯然跟本段主題不一致，我們需要將其去掉：
<√>
Excel提供一個組織資料的高效方法。我們可以將Excel想象成一個有行和列的二維表格，每一行代表一個獨立的實體，每一列代表該實體的不同屬性。如果你想使用Excel來記錄圖書資訊，那麼每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價格以及出版社等等資訊。
5.2 好的開頭語
除了要保證段落的“單一職責”之外，我們還需要給每個段落一句“好的”開頭語。那麼什麼是好的開頭語呢？好的開頭語要能讓讀者讀完之後就能猜到文件作者在本段中想要陳述的主題，其實就是概括性的句子。還是以上面那段話為例子，它的第一句話“Excel提供一個組織資料的高效方法”其實就是很好的開頭語，它提示本段內容主要講Excel如何高效地組織資料。如果我們將上面那段話的開頭調整一下，那麼效果明顯就差了很多：
<×>
Excel由許許多多的單元格組成，每個單元格可以包含不同的內容。我們可以將Excel想象成一個有行和列的二維表格，每一行代表一個獨立的實體，每一列代表該實體的不同屬性。如果你想使用Excel來記錄圖書資訊，那麼每一行代表不同的書本，每一列代表書本的屬性，比如書的名稱、價格以及出版社等等資訊。
讀者讀完上面第一句話後，可能還是很懵，需要讀完整段話才能明白文件作者在本段中想要表達的意思。段落的開頭語可以通過提煉段落內容得到，我們可以在段落寫完之後回過頭提煉一句話作為本段的開頭語，下面這段話描述程式碼中迴圈語句的作用：
<×>
目前幾乎所有的計算機程式語言都支援迴圈語句，例如，我們可以編寫程式碼來判斷一個使用者命令列輸入是否等於“quit”（退出命令），如果需要判斷100萬次，那就建立一個迴圈，讓判斷邏輯程式碼執行100萬次。
上面的這段話本身沒什麼問題，主要介紹迴圈語句的功能和應用場合。但是如果我們提煉一下，在段落開頭增加一個更好的開頭語，效果可能會提升很多：
<√>
迴圈語句會多次執行同一個程式碼塊，直到不再滿足迴圈條件為止。目前幾乎所有的計算機程式語言都支援迴圈語句，例如，我們可以編寫程式碼來判斷一個使用者命令列輸入是否等於“quit”（退出命令），如果需要判斷100萬次，那就建立一個迴圈，讓判斷邏輯程式碼執行100萬次。
上面開頭第一句話就說清楚了迴圈結構的特點，讀者讀完第一句話基本就知道整段內容要講什麼。一個好的開頭語能夠節省讀者的時間，因為並不是每個讀者都有興趣去閱讀整段的內容，開頭語可以給讀者“是否繼續讀下去”一個參考。
5.3 控制段落長度
控制段落長度並沒有一個明確的標準，它只是一個非常主觀的說法。如果文件中某個段落內容太長（比如那種一段話就佔半頁Word），作者自己應該反覆閱讀幾次再對段落做一些精簡，這樣既可以節省讀者的時間，大概率也能提升意思表達的準確性。同樣，也不太建議文件頻繁出現小段落，比如整段內容只有一兩句話那種，這個時候可以考慮段落合併或者稍微擴充一下內容。
最後我們來總結一下，在技術型文件中如何正確使用段落：
- 一個段落只負責講一個內容，兩個不同的主題應該拆分成兩個段落去陳述；
- 儘量為每個段落增加一個“好的”開頭語，能夠清晰表達（或暗示）本段的主題；
- 要控制好段落內容長短，“不長不短”根據自己經驗（比如不超5~7個句子）。
6 適當使用列表和表格
文字相對來講其實是一種效率比較低的表達方式。如果你想讓人快速地去理解你要表達的意思，圖片應該是最好的一種方式，但是圖片有一個缺點就是：有時候它只能從巨集觀上去表達，無法體現其中細節。當我們想要儘可能直觀地去陳述內容，又想盡可能多的包含細節時，我們可以考慮使用列表或者表格。有些讀者非常牴觸大段大段的文字（尤其在技術型文件中），一種改進方法是前面提到的“控制段落長度”，儘量讓段落內容精簡、單一；再一個就是看看段落內容是否能以列表或者表格的方式去呈現，這種方式可以給人“嚴謹、清晰”的感覺。
6.1 使用列表
列表簡單來講就是將你原來用段落方式呈現的內容改用專案（Item）的方式去呈現，一般它主要用於列舉、過程描述或者要點歸納等場合。列表中的各項可以是名詞、短語，甚至是句子，各專案之間有嚴格順序要求的列表叫“有序列表”，相反並沒有嚴格順序要求的列表叫“無序列表”。下面是以段落的方式陳述小張今天所做的事情：
白天在公司上班期間，小張一共修復了7個bug，做了3個程式碼合併（評審），並和專案經理討論了前天提的新需求。晚上回到家後，小張先做飯，然後給兒子洗澡，23:30上床睡覺。
上面這段話本身沒什麼問題，用了合理的標點符號和過渡詞，讀起來清晰明瞭。但是，如果在技術型文件編寫中，能將這段話改用列表的方式呈現，起到的效果會更好：
小張白天在公司：
- 修復了7個bug；
- 做了3個程式碼合併（評審）；
- 和專案經理討論前天提的新需求。
晚上回到家後：
- 做晚飯；
- 給兒子洗澡；
- 23:30上床睡覺。
我們將原來的一段話拆成了兩個列表，並在每個列表前面做了一個“引入說明”（以冒號結束），介紹了接下來列表的背景上下文。第一個列表是無序列表，因為原文並沒有突出強調小張白天在公司每項工作之間的前後關係（無順序要求），只是一個歸納統計；第二個列表是一個有序列表，原文很明顯強調了小張晚上回家之後做事的先後順序（最後一項還給出了具體時間）。在技術型文件中，合理地運用列表這種方式去呈現內容可以給人一種“邏輯嚴謹、思路清晰”的感覺，讓讀者更相信你講的內容。
在使用列表時，我們應該確保列表中各項內容結構一致，即：要麼都是名詞，要麼都是短語，要麼都是句子。這個原則既能保證你使用列表的初衷（邏輯嚴謹、思路清晰），也能讓讀者讀起來更舒服。下面是一個錯誤使用列表的示範：
<×>
影響系統檢測準確性的因素有：
- 模型；
- 產品開通過程中，工程師對演算法引數校準程度；
- 應用現場是否有燈光照明。
上面列表一共包含3項，每項的內容結構各不相同，第一項是一個名詞，第二項是一個句子，第三項是一個短語。我們將結構統一後，可以調整為下面這樣：
<√>
影響系統檢測準確性的因素有：
- 模型的複雜性；
- 部署時對演算法引數校準的程度；
- 應用現場是否有燈光照明。
上面是將列表中各項內容修改為短語，我們還可以換另外一種方式：
<√>
影響系統檢測準確性的因素有：
- 模型型別
- 校準程度
- 環境亮度
上面是將列表中各項內容修改為名詞，由於是名詞，每項結尾處不使用任何標點符號（參見前面專門講標點符號的章節）。下面是對列表運用的總結：
- 列表一般用於列舉、過程描述、要點歸納等場合；
- 需要強調順序的時候應該使用有序列表，其餘視情況而定；
- 列表中各項內容結構應保持一致，都是名詞、短語或者句子；
- 每個列表前面儘量新增一個明確的“引入說明”，以冒號結束。
6.2 使用表格
表格其實跟物件導向有一定聯絡，大部分時候表格中的一行相當於一個物件，表格中的列相當於物件的屬性（欄位），表格和麵向物件組織資料的方式本質上是一致的。技術型文件中表格一般用來組織與數字有關的內容，當然也有例外，就像前面章節中用到的表格，純粹是為了組織文字內容。
下面是在技術型文件中，使用表格時可以參考的一些經驗：
- 組織數字相關內容時，一定要用表格（大部分人可能已經有這個意識）；
- 組織結構化型別的文字內容時，儘量用表格；
- 每個表格都應該配一個表格標題，簡要說明表格內容；
- 文件中的表格應具備一致的樣式和風格，比如標題字型、背景填充等。
在技術型文件中使用表格組織文字內容時，需要控制每個單元格的文字長度。一般情況下建議單元格中只使用短語，如果必須要用段落，也應該控制段落中句子數量（一般建議不超過2~3句）。下面是錯誤使用表格來組織文字內容的示範：
表6-1 三種程式語言介紹
| 序號 | 語言 | 介紹 |
|---|---|---|
| 1 | C | C語言由貝爾實驗室發明於1969至1973年，是一種編譯型計算機程式語言。它執行速度快、效率高、使用靈活，常被用於計算機底層驅動以及各種語言編譯器的開發。C語言是一種程式導向的程式語言，同時它的語法相對來講較複雜，新人入門門檻比較高。 |
| 2 | C++ | C++語言發明於1979年，是一種編譯型計算機程式語言。它衍生自C語言，繼承了C語言的一些特性，比如使用指標直接訪問記憶體，同時它也支援物件導向程式設計，提升了程式碼的可複用性、可擴充套件性以及靈活性。由於C++繼承了C的大部分語法，再加上本身具備複雜的型別系統以及泛型程式設計等語言特性，新人入門門檻也比較高。 |
| 3 | Python | Python語言發明於1991年，是一種解釋型計算機程式語言，因此執行速度相對要慢。Python除了支援物件導向程式設計之外，還支援函數語言程式設計，它語法簡單，更貼近人類自然語言，新人入門門檻較低。Python是目前人工智慧領域最熱門的語言，對應的工具庫非常豐富。 |
上面是以表格的形式來介紹C、C++以及Python三種程式語言，但是在“介紹”那一列中的文字內容太長，我們可以換一種表達方式：
表6-2 C vs C++ vs Python
| C | C++ | Python |
|---|---|---|
| 由AT&T 貝爾實驗室發明於1969至1973年 | 由BJarne Struistrup發明於1979年 | 由Guido van Rossum發明於1991年 |
| 語法比較複雜，新人入門門檻高 | 語法比較複雜，新人入門門檻較高 | 語法簡單，貼近人類自然語言，新人入門門檻低 |
| 編譯型語言 | 編譯型語言 | 解釋型語言 |
| 支援程式導向程式設計 | 支援程式導向、物件導向程式設計 | 支援程式導向、物件導向、函數語言程式設計 |
| 偏底層、執行速度快、使用靈活 | 繼承了C語言的一些特性，在其基礎之上還支援物件導向等特性 | 語法簡單，學習難度低 |
| 一般用於驅動、編譯器、嵌入式或者其他偏向硬體層面的開發 | 一般用於遊戲前後端、PC客戶端的開發 | 一般用於資料科學、人工智慧相關開發 |
上面表格一共還是3列，但是現在每列代表一種程式語言，列中的每個單元格是對該語言的描述，描述內容都比較精簡。如果你想繼續補充內容，可以對應地增加行即可。表格的組織方式有多種多樣，行可以變成列、列可以變成行，並沒有嚴格的限制。我們只需要找一個適合自己的方式，比如上面這種每列代表一種語言，是因為該場景需要介紹的程式語言只有三種，如果數量再多點（或者數量不確定，後期會繼續增加），那麼表格寬度就不太夠、這種組織方式就不再合適。
7 一圖勝千言
人類在發明文字媒介之前，用的是圖形符號。影像（或圖形、圖片）是所有內容表達方式中最直觀的一種，同時也能提升讀者的閱讀興趣。有人專門做過研究：在文件中增加影像能提升讀者對文件的喜愛程度，不管這個影像跟文件內容本身是否有關係（論文連結）。也就是說，哪怕在文件中插入無關緊要的影像，讀者也更願意去嘗試閱讀文件中其他的內容。我們平時看別人演示PPT時，如果發現整頁都是文字描述，大概率就不會有認真去聽的慾望。下面是一段對雙向連結串列的文字描述：
| × |
|---|
| 雙向連結串列也叫雙連結串列，是連結串列的一種。它的每個資料節點中都有兩個指標，分別指向直接後繼節點和直接前驅節點。所以，從雙向連結串列中的任意一個節點開始，我們都可以很方便地訪問它的前驅節點和後繼節點。在應用雙向連結串列時，我們一般構造雙向迴圈連結串列，連結串列首尾相連。 |
上面這段描述雙向連結串列的文字本身已經非常清晰，對資料結構有一定基礎的人看完文字基本就能理解雙向連結串列的結構和應用場合（基於它的特點）。但是，如果是一個零基礎的小白來看這段話，可能效果就不會太好（尤其如果這段話是作為PPT中的內容，大概不會再有更多的內容補充）。如果我們在這段話後面增加一個插圖，來直觀告訴讀者雙向連結串列長什麼樣：
| √ |
|---|
雙向連結串列也叫雙連結串列，是連結串列的一種。它的每個資料節點中都有兩個指標，分別指向直接後繼節點和直接前驅節點。所以，從雙向連結串列中的任意一個節點開始，我們都可以很方便地訪問它的前驅節點和後繼節點。在應用雙向連結串列時，我們一般構造雙向迴圈連結串列，連結串列首尾相連。下圖是雙向連結串列結構示意圖：  圖1 雙向連結串列結構 |
上面的文字配合圖片，能讓讀者更加直觀的理解雙向連結串列的結構特點。當文件中的文字和圖片同時出現時，讀者大概率會先看圖片，然後再結合文字去理解，加快文件閱讀速度。
7.1 可抽象也可具體
技術型文件中的插圖不一定都得是流程圖、架構圖、或者結構設計圖這種非常具體的技術相關圖片，還可以是抽象的、能形象表達文件主題的圖片。下面是在技術型文件中使用卡通和漫畫圖片的示例：
| √ |
|---|
| <示例1> Gitlab中有Label和Tag兩個概念。  <示例2> 原始碼版本控制系統（Source Code Version Control System）主要負責對原始碼版本進行管理，涉及到程式碼提交、撤銷、比對、分支管理、程式碼合併等功能。原始碼管理是軟體開發過程中非常重要的一個環節，它能有效保證軟體程式碼質量。  圖1 團隊協作 原始碼管理並不是軟體開發週期的全部，整個軟體開發週期涉及到多個流程、多個團隊（多人）協作完成，包括立項/結項、進度/任務管理、需求/設計、bug管理、測試、整合上線等環節。 |
7.2 突出圖中重點
當我們想為文件新增圖片時，單張圖片包含的內容不宜太過複雜，圖片應該能準確地表達意思。如果一張圖太過複雜、或者包含了一些可能引起歧義的部分，我們可以嘗試以下兩種改進方式：
- 將複雜的圖拆開，一張圖對應一個區域性細節；
- 在圖片中將重點區域標記出來，讓讀者可以一眼就發現重點。
在技術型文件中插入複雜的系統架構圖很常見，這種時候建議遵循“先巨集觀，再具體”的原則，循序漸進。我們不要一上來就放一張大圖，還想將所有的細節都包含進去，這種想法不太現實，這不僅對你畫圖的技能要求很高，讀者看完也容易一臉懵。下面這張圖太過複雜：
| × |
|---|
整個視訊分析系統由3大服務組成，分別是Intelligent Video Analytics、Front Video Service以及Distribute Load Balance，這3大服務一共包含15個子模組。下面是視訊分析系統結構： 圖1 視訊分析系統結構 |
上面這個例子中插入的這張圖既想描述3大服務之間的互動關係、又想描述各個服務內部子模組之間的互動關係（上面只是示意圖，實際情況可能比這個更復雜）。文件讀者碰到這種情況可能會產生兩個感覺：一是圖太複雜了，很難看懂，有些地方迫於空間原因字號還小；二是我需要重點關注的點在哪裡？如果遵循前面提到的“先巨集觀，再具體”的原則，上面這個例子可以調整為：
| √ |
|---|
整個視訊分析系統由3大服務組成，分別是Intelligent Video Analytics、Front Video Service以及Distribute Load Balance。下面是視訊分析系統中各服務之間的關係： 圖1 視訊分析系統服務互動 其中，Intelligent Video Analytics服務主要負責對視訊解碼、推理以及行為分析等結構化操作。該服務內部一共包含9個子模組，模組之間的關係見下圖：  圖2 Intelligent Video Analytics服務子模組互動 Front Video Service服務主要負責視訊接入、分發、配置管理等功能。該服務內部一共包含3個子模組... |
另外一種情況，插入的圖片中包含了不相干內容，文件作者又沒有給出醒目的標記，讀者看完不清楚關注重點在哪裡。下面是錯誤的示例：
| × |
|---|
Gitlab中的Release功能主要用來對倉庫中的程式碼以及其他一些相關資料檔案進行歸檔，通常用於版本釋出。當有新版本釋出時，使用者可以基於對應的Commit建立一個Tag標記，給它一個合理的名字，比如“v1.0-pre”（代表釋出1.0預覽版），然後再基於該Tag釋出版本。後期，其他人可以通過Release選單快速瀏覽、檢索專案版本釋出記錄以及對應時間點的相關程式碼和資料。使用者可以在Gitlab主介面的左側選單中找到Release功能入口： 圖1 Gitlab中Release選單 |
上面圖片在介紹Release功能時給出的圖片中包含的選單項太多，為了讓讀者更直觀看懂圖片關注點，可以將圖片調整如下（左右兩種都可以）：
| √ |
|---|
Gitlab中的Release功能主要用來對倉庫中的程式碼以及其他一些相關資料檔案進行歸檔，通常用於版本釋出。當有新版本釋出時，使用者可以基於對應的Commit建立一個Tag標記，給它一個合理的名字，比如“v1.0-pre”（代表釋出1.0預覽版），然後再基於該Tag釋出版本。後期，其他人可以通過Release選單快速瀏覽、檢索專案版本釋出記錄以及對應時間點的相關程式碼和資料。使用者可以在Gitlab主介面的左側選單中找到Release功能入口： 圖1 Gitlab中Release選單 |
7.3 有準確的圖示題
圖片是為了讀者能夠更直觀地理解文件內容，但是圖片畢竟不是文字，不同的人對同一張圖片理解可能存在差異，尤其對於那種不包含任何文字的圖片。因此，在文件中插入任何圖片時，我們應該為它定義一個合適、貼切的標題。圖示題一般是一個名詞或者短語，作用跟前面講到的表格標題一樣，協助讀者理解圖片所要表達的含義。
8 統一樣式和風格
文件的樣式和風格其實跟我們寫程式碼一樣，寫程式碼要遵守統一的程式碼風格（變數命名、換行規則等等），寫文件也應該遵守統一的文件風格。公司或者組織一般都有自己的文件風格規範，規範會定義好正文/標題字型字號、頁首頁尾、頁邊距、行間距、段前段後間距等等，按照規範寫出來的文件風格基本就能保持一致。
對於沒有規範可用的場合，文件作者可以根據自己的偏好執行即可，保證整篇文件的內容遵守相同的風格，比如文件開頭和文件結尾的段落間距、列表樣式、對齊方式都應該保持一致。本篇文件的主要規範定義如下：
- 頁邊距上下左右2cm；
- 標題18號華文仿宋，正文12號宋體，正文中表格/圖示題12號華文仿宋；
- 段前/段後間距0.5，段落行間距1.5倍，段落首行對齊不空格；
- 表格、圖片居中對齊，圖示題在圖片下方、表格標題在表格上方。
還有另外一些比較重要的樣式定義，比如列表樣式（本篇文件中每個列表外面套了一個表格，表格無左右邊框），還比如本篇文件涉及到了很多舉例和示範，所有的舉例示範都在表格中，並且表格有自己的樣式（字型字號、背景顏色等等）。
9 把握好整體文件結構
把握好整體文件結構是一件非常困難的事情，這個其實跟前面講到的文件內容本身沒什麼關係。文件作者在動筆之前需要有一個巨集觀的構思，需要在腦子裡先將文件大綱梳理一遍，一級標題可以是什麼、二級標題又可以是什麼，然後考慮將合適的內容放到對應的章節中去。優秀的作者在正式動手之前，可能已經有了很長一段時間的思考準備，尤其對於那種非常複雜的文件。但是這種方式對一些人來講可能不太現實，難度太大。那麼這時候就只能考慮另外一種方式，動手之前先在白紙上打草稿，列出來文件大綱，然後不斷修改和調整，直到滿意為止。
其實不管上面哪種方式，文件結構考驗的是作者組織內容的思維能力。對於一些需求、設計型別的“主流”技術型文件，考驗的是作者對軟體需求、系統架構的理解深度，該寫什麼不該寫什麼，寫到什麼程度，這些都需要作者考慮清楚，這型別的文件一般有標準的模板可以參考，大家平時寫得/見得也比較多。對於另外一些“非主流”型別的技術型文件，比如對某個線上問題的分析報告、技術/原型調研類文件，這些文件一般規模比較小、也沒什麼參考標準，全靠作者自己去組織。
下面就以“對某個使用者需求做技術性反饋”為例，拋磚引玉，簡單描述一下技術型文件結構應該如何去組織：
<場景說明>
視訊分析系統中，客戶要求在事件錄影檔案中對涉事車輛目標（或區域）進行高亮標框顯示，視訊錄影在播放時會有一個醒目的多邊形提醒使用者具體事件發生位置。客戶懂一些技術相關知識，要求公司技術研發團隊針對該需求給出合理的需求反饋，如果需求可實現，評估工作難度；如果需求不可實現，說明具體原因。
根據上面場景說明，該需求並非硬性要求。甲方提出了一個想法，並且非常貼心地考慮到了乙方是否具備條件實現，希望給出一個實質性的答覆。公司技術團隊在寫反饋說明文件之前，應該考慮以下兩個問題：
- 如果正常響應該需求，具體的方案是什麼、難點/風險點各是什麼；
- 如果不能正常響應該需求，具體原因是什麼，是否有可替代方案、替代方案是什麼。
也就是說，不管最終團隊是否響應該需求，我們在文件中都要有非常實質性的內容，不應該是空話、套話。下面就以“不響應”為例，描述文件應該包含哪些內容：
| 序號 | 節標題名稱 | 主要內容 |
|---|---|---|
| 1 | 背景說明 | 用自己的話將客戶的需求完整描述一遍，不要有任何偏差，表明我方已認真理解過原始需求。 |
| 2 | 已有錄影邏輯 | 詳細描述系統中目前已有的事件錄影邏輯。因為我們本次是不響應該需求，所以對後面不響應有利的內容一定要著重強調（要突出已有錄影邏輯的優勢）。 |
| 3 | 錄影標框邏輯 | 詳細描述在事件錄影檔案中對涉事目標（或區域）進行高亮標框的邏輯。注意這裡按照理想邏輯去描述，不用考慮任何外在限制。 |
| 4 | 錄影標框難點 | 結合第3點，重點歸納、整理出在錄影檔案中標框的難點，比如需要對每一路進行解碼再去疊加圖形、視訊畫面不能壓縮否則影響解析度等等，這些對裝置效能要求非常高，會增加硬體成本。 |
| 5 | 解決方案一 （不計代價去響應） | 按照理想邏輯去響應，但是要提出前提條件或者代價，比如單臺裝置分析路數降低到原來的一半，硬體成本是原來的2本。（其實就是要排除這個方案） |
| 6 | 解決方案二 （可替代方案） | 提出一種可替代的方案，可以滿足客戶最開始提出的“有醒目標記提醒使用者”。比如當視訊錄影播放時，可以在播放器上面疊加一個高亮方框，能夠大概標記涉事車輛目標（或區域）。同時，強調該方案的優勢（比如工作週期短、對成本無影響）。 |
| 7 | 結論 | 其實根據前面的描述，只要認真讀完文件的人基本都能知道結論是什麼、應該選哪個方案。但是這裡還是要書面寫上，根據前面的描述，解決方案二有更大的優勢，建議採用方案二。 |
需要注意的是，“響應”或者“不響應”的決定很多時候不在技術團隊或者寫這個文件的人手裡。雖然文件中的內容應該為最終的結論服務，但是總體上不應該有偏差。
10 明確文件的目標群體
文件的目標群體是誰？這個其實應該是寫文件最開始就需要明確的東西，面對不同的群體，我們文件的內容、結構包括內容描述程度都會不同。儘早確定讀者有助於在構思階段就明確文件內容邊界，哪些該寫、哪些不該寫，該寫的又應該如何去寫，這些都是編寫文件的大方向。