專家教你系列：寫一篇好技術文章的經驗秘籍，全在這兒了

,## 前言

對于軟件工程師來說，編碼能力的重要性自不必說，技術寫作的能力也相當重要。一篇好的設計文檔能夠指導需求的開發測試，提升軟件質量；一篇好的用戶文檔能夠幫助用戶迅速熟悉軟件的使用方法；一篇好的技術博文可以讓人耳目一新，受益匪淺；一篇好的經驗總結可以讓新手們少走彎路。

技術寫作的目的是讓讀者能夠順利地使用一個軟件或理解一項技術或弄懂業務流程。它與創作型寫作的最大區別在于，技術寫作并非為了取悅讀者，而是追求以簡潔和精確的文字去闡明事實。

一篇好的技術文章應該能夠讓符合條件的讀者，在良好的閱讀體驗下，理解甚至掌握文章所要傳達的內容。

技術寫作是一項學問，很多同學或多或少都有寫些技術文章的想法，但因為缺乏一些基本的寫作技巧，常常無從下手。本文將給出一些技術寫作的建議，力求讓軟件工程師們能夠寫好技術文章，愛上技術寫作。

為什么要技術寫作

提升表達能力

如何組織文章，如何將復雜的技術原理通俗易懂地表達出來，這都非常考驗人的表達能力。

加強架構和邏輯思維

文章如同軟件，也有架構和邏輯。博士們的架構和邏輯思維之所以普遍強大，一個很重要原因是他們都經過了嚴格的論文寫作磨練。當我們把文章寫好時，架構和邏輯思維會得到增強，軟件設計和開發能力也能隨之提高。

加深對技術/業務的理解

展示自我

通過技術文章來分享知識是一個很好的展示自我的途徑，讓大家知道你當前熟悉的領域，逐漸擴大自己的影響力，對后續的職業發展可以起到很大的幫助。

心靈愉悅

在公開平臺上發表技術文章，收獲很多瀏覽量，被讀者評論，得到讀者和，這些都能夠讓人得到心靈上的愉悅。

如何開始技術寫作

所謂萬事開頭難，對習慣于與代碼打交道的軟件工程師來說，要開始與文字打交道的技術寫作，很難。相信很多同學都遇到過憋了幾個小時都沒寫出幾個字，或者一直在糾結寫什么內容的窘境。其實，只要找到一些方法，著手技術寫作，并沒那么難。

從記錄學習/工作內容開始

可以先從記錄日常的學習/工作內容開始，慢慢習慣與文字打交道，此過程重在建立起寫作的自信。

文章長短不重要

不要一開始就想著寫出驚駭世俗的文章，成為最出色的技術博主。也并非只有長篇大論才算得上好的技術文章，一些問題解決記錄、經驗總結的短文也能給讀者很大的幫助。

通過學習找到寫作靈感

如果你還在為要寫什么內容而焦頭爛額，那么就去學習一項新的技術或者去閱讀一本書吧。最好的寫作時機就是剛學到知識的時候，因為這時你很清楚從零到一的過程，這也是你要傳遞給讀者的東西。

學會做筆記

筆記是很好的寫作素材，在日常的工作和學習中多做些筆記，把自己的靈感記錄下來，后面寫作起來也會輕松許多。

寫作的三部曲

第一步：立下寫作目標

寫作的第一步是立下目標，明確要寫哪一類的文章，并朝著目標去寫作。比如，立下了介紹Java中HashMap數據類型的目標，就不要在文章上描述JVM的垃圾回收原理，這是混淆了寫作目標。

第二步：確定受眾讀者

寫作的第二步是確定受眾讀者，只寫這類讀者可以接受的知識。比如，要寫一篇題目是《從零開始學習Java語言》的文章，這明顯是一篇針對Java初學者的文章，那么就不要在文章里剖析JVM內存管理的實現源碼，這是混淆了文章受眾。

第三步：組織文章

組織文章就是根據中心旨意，把要表達的知識串聯成一篇條理清晰的文章。很多新手都會面臨“心中想法萬千，卻無從下筆”的困境，這就是缺乏文章組織導致的。《文心》一書中有提到：

對于文章的組織，也不妨舉出一個總方法來，那就是 ‘回問自己’ 四個大字。

我們可以通過“回問自己”的方法來組織文章，以《教你寫好代碼注釋》一文為例：

“是為了要說些什么才寫這篇文章的？”

—— 為了總結些寫好代碼注釋的方法。這樣文章的中心意旨就明確了。

“中心意旨在我們意念中間是怎么來的？”

—— 讀到《A Philosophy of Software Design》一書中關于代碼注釋的章節深有感觸，想分享給大家。這樣文章依據的材料范圍也就確認了。

“這個材料可以增加中心意旨的力量嗎？”

—— 書中關于high-level注釋和low-level注釋的例子可以很好地體現“什么是好的代碼注釋”這個旨意。這樣就可以不斷篩選出好的素材，文章的主要內容也就確認了。

“還有更簡練通順的表達嗎？”

—— 這樣寫好像更通順一些。這樣經過不斷的修正，一篇文章也就出來了。

一些技術寫作建議

1 熟悉寫作內容

2 寫作前先列大綱

文章不僅僅是把內容羅列出來，要注重知識的表達，因此需要一個清晰的文章架構。在寫作前先列出大綱，能夠幫你理清寫作思路，確認內容是否符合邏輯，構建清晰的文章架構。多想想，哪個內容需要先闡述？段落的順序要怎么排？哪些知識需要更多的解釋？哪些點到為止即可？

3 精簡文字

技術寫作不是劇本小說，不需要反轉曲折的劇情，更不需要含沙射影的表達，它追求的是直接、實用、清晰明了的表達風格。沒必要使用過于復雜的文字去描述技術原理，這只會讓它們更加難以理解。使用簡潔的文字，多用短句，能夠讓文章可讀性更好。

4 多舉例子

避免通篇介紹技術原理的寫作，這會讓文章過于枯燥，內容也晦澀難懂。要多舉例子，它不僅能讓技術原理更易懂，也能讓主題更加深刻。比如在《教你寫好代碼注釋》中，通過舉例正反面的代碼注釋，更能讓讀者對好的代碼注釋產生共鳴。

5 善用圖表

有時候，我們會遇到很難用文字，或需要用很多文字才能描述清楚的東西，比如復雜的業務流程和模塊依賴。這時可以使用圖表來可視化表達，一張恰當的圖表能夠清晰地闡明技術原理，勝過千言萬語。

一些畫圖軟件推薦

適合新手：MicroSoft Office PowerPoint、MicroSoft Office Visio、Apple Keynote

在線畫圖：Draw.io、ProcessOn、Excalidraw

代碼繪圖：PlantUML

手繪風格：Apple Keynote、Excalidraw

高級玩家：Sketch、Lunacy

6 代碼分段

在深度剖析一些技術原理或系統框架時，我們往往都會涉及源碼分析，切忌直接在文章中貼上上百行的代碼，然后在代碼前/后用一段文字對其說明。這會導致讀者為了將代碼和說明對應上，而頻繁上下翻頁，嚴重影響閱讀感受。

反面教材：

... inline void* oopDesc::field_base(int offset) const { return (void*)&((char*)this)[offset]; } template inline T* oopDesc::obj_field_addr(int offset) const { return (T*)field_base(offset); } // 剩余上百行的代碼 ...

由上述代碼片段可知，每個field在oop中都有一個對應的偏移量（offset），xxx。

更好的方法是將代碼分段講解，并在在其中穿插關鍵注釋。

正面例子：

// 獲取field前需要先判斷是否采用了指針壓縮技術，先根據offset調用obj_field_addr // 得到field的地址，然后調用load_decode_heap_oop得到實例 inline oop oopDesc::obj_field(int offset) const { return UseCompressedOops ? load_decode_heap_oop(obj_field_addr(offset)) : load_decode_heap_oop(obj_field_addr(offset)); }

oopDesc::obj_field方法主要用于xxx。

// 基礎類型特有的實現與obj_field_addr類似，只是轉型成特有的基礎類型指針 inline jbyte* oopDesc::byte_field_addr(int offset) const { return (jbyte*)field_base(offset); }

oopDesc::byte_field_addr主要用于xxx，在xxx時會被調用。

7 反復修正

好的文章都是經過反復的修正才誕生，不僅僅局限于錯別字和用詞的修改，要以讀者，甚至是審稿人的視角去審視整篇文章。怎么才能讓這段內容表達更清晰？哪些知識需要延展？哪些片段可以裁剪掉？

養成在發布前仔細閱讀一遍文章的習慣，杜絕低級錯誤，這也是對讀者最大的尊重。

8 做好排版

如同代碼需要分段講解，文字也需要分段，一大段的文字容易讓人覺得枯燥。對重點語句/詞語需要加粗突出；善用標題、有序/無序列表來羅列知識點，讓文章看起來更加清晰。

推薦使用markdown進行技術寫作，它排版簡潔美觀，語法簡單，而且絕大多數的平臺都支持markdown格式的文章發布。另外，還可以使用markdown-nice等排版工具自定義文章背景、色彩、字體等，提升閱讀觀感。

9 讀好的文章

養成讀好文章的習慣，學習他們的寫作方式，不斷提升自己的寫作技巧。

總結

《文心》將文章寫作歸結為三個階段：習作、應用和創作。

習作只是法則與手腕的練習，應用之作只是對付他人和事務的東西，創作才是發揮自己天分的真成績。

這三者之中，最基本、最重要的是習作。只有當習作到了相當的程度，才能有應用，也才能談得上創作。

上面介紹了很多寫好技術文章的方法，但最簡單，也是最有效的方法是：不要停止寫作。

參考

文心, 夏丏尊/葉圣陶

技術文章如何寫作才能有較好的閱讀體驗, 伍迷

Technical Writing: Definition and Observations, Richard Nordquist

15 Tips to Improve Your Technical Writing, TBS Staff

Advice for Technical Writing, Chris Coyier

Developers: The Why and How to Writing Technical Articles, Goodness Kayode

專家 軟件開發

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。