## 技術文章寫作規范  網上有大量的技術文章，內容質量參差不齊，有的傳播廣，有的卻默默無聞，而那些傳播最廣的不一定是內容質量最高的，而默默無聞的往往也不是因為內容質量低。 還有一些文章，都是一些碎片化的知識內容，有的甚至有明顯的錯誤，有的閱讀起來很費力，引用的內容找不到出處和證明……，等等這樣的問題，這讓我們平時在網上搜尋資料時相當不容易。 鑒于此，本文遂總結一些技術文章的寫作規范和技巧，掌握這些有利于提高寫作質量。 ***** ### 1. 保持簡潔和準確語義 “這兒多了一個空格，下面 sql 語句執行失敗了。” “這兒多了一個空格，導致下面 sql 語句執行失敗。” 你感受一下這兩句話，表達的是同一個意思，但是明顯下面一句話讀起來更好，好在哪里又似乎說不出來，其實下面一句話，意思更加明確。 大多數時候，我們看文字，看東西的時候，都是一目十行（**眼睛和大腦并不同步，閱讀十行，但其是大腦并沒有逐字地去看**），模糊的意識、潛意識的（**很多時候大腦是根據殘存的記憶或過往的經驗去接收和理解信息的**），如果表達不清晰，很容易就理解偏了意思，而如果文章表達的意義簡單易懂，那么我們一目一行的看過去就不會出現問題，否則有的段落我們還要來來回回看幾遍才行，這是失敗的寫作。 觀點鮮明，用詞直接，簡單，語句通順，讓人讀起來不吃力，感覺就是這般樣子，這就是行文流水的境界吧。 如果我們需要表達某個觀點時，請用語義更加明確，直接，簡單的方式表達出來。這就是說話的語義化。 > 還有，能用肯定的就不要用雙重否定。 * * * * * ### 2. 作者應該保持中立 當一件事物有兩種或多種觀點時，作者應該先闡述每一種觀點，將評判留給讀者自己去判斷。不要加入自己的觀點以傾向于某一種，從而客觀影響讀者自己的判斷。 當然，不要誤會，要求作者保持中立并不是說作者不能沒有自己的看法，只是說不要把自己的意愿強加給讀者，而要給讀者開放的思想。當作者詳盡的闡述完后，最后再表明自己的觀點和看法，這是可以的，我們鼓勵這樣。但不要發表沒有依據的觀點，和加入自己的意志來客觀引導讀者，這正是我們反對的。 同時還應當注意的是，當作者的觀點不被讀者接受，甚至收到批評的時候，要能夠包容不一樣的聲音，因為：如果批評不自由，則贊美無意義。 * * * * * ### 3. 語氣不應過分帶有個人色彩 我認為，技術類文章應該是嚴謹的，語言用詞都應該是準確的。這里所說的嚴謹不是說文章一定要保持那種教條式的刻板，幽默有趣也未嘗不可，但是不能過了，如果文章風格和字里行間透露著作者個人個性化的東西（如：作者的口頭禪、俗語、過分俏皮賣萌和無厘頭以及嘻哈風），那么這樣的文章就算再好，受眾也不會很廣。 技術文章不同于一般性文章，它的受眾沒有界限，沒有年齡、性別、地域、種族的界限，都應當被每個人平等的觸及到的。所以在寫技術文章時，作者的文風應該保持嚴謹，不應該過分加入自己的性格色彩，這樣的文章才易于閱讀和廣泛傳播。 ***** ### 4. 多采用分段的方式 不同于寫作文和散文，技術文章對格式沒有特別的要求，只要保持簡潔，結構清晰就可以了，而要想做到結構清晰，最好的方式就是分段。類比技術文檔，技術文章其實是最容易采用分段寫作的了。 如每一個大的技術點都可以作為一個大的段落，并且為每一段起一個標題，根據內容長短和復雜度，甚至還可以以章節的形式分篇書寫。多嘗試，很快你就能掌握這個技巧，這樣你寫的文章再也不會是那種冗長，密密麻麻，令人生畏的了。 ***** ### 5. 寫作時間/背景 很多時候作者有必要給出寫作的時間，必要的時候還需要交代寫作的背景，因為隨著時間流逝，很多東西可能都發生變化了，如果作者寫作時備注清楚了寫作時間，將會在未來給讀者閱讀時提供幫助和參考，以讓其更好的理解內容。 另外考慮到軟件行業發展迅速，環境更迭往往會使舊代碼很快過時，所以對于重要的代碼演示部分，作者甚至有必要給出自己當時測試的環境信息：機器型號，依賴庫，軟件版本等詳細信息。這樣做不僅顯得更加專業嚴謹，也方便了讀者，避免了讀者調試運行時結果與文章中不一致的問題。 ***** ### 6. 引用來源 如果你的文章有引用外部資料或寫作時參考了其它資料，就務必要在文中或文末給出來源，包括但不限于，參考資料、文獻、實驗數據、佐證等。有了這些文章才算是完整的，立體的，才是可信的，因為它確保了成文有據可依，有源可溯，這對讀者來說是非常有益的。并且交代出處也是對讀者負責和對原引用的一種尊重的體現。 * * * * * 本文會一直保持更新狀態，大家有好的心得見解可以在下面留言討論。 ***** ### 參考資料 [中文技術文檔的寫作規范 - 阮一峰的網絡日志](http://www.ruanyifeng.com/blog/2016/10/document_style_guide.html) [mzlogin/chinese-copywriting-guidelines: Chinese Copywriting Guidelines：中文文案排版指北（簡體中文版）](https://github.com/mzlogin/chinese-copywriting-guidelines) [這個房間的消音高達99.99％！安靜到能聽到自己腸胃蠕動的聲音！](https://www.365yg.com/a6536155986007163396) [信息與大腦 · 產品設計 · 看云](http://www.hmoore.net/xiak/product/679861) [中文文案排版指北 chinese-copywriting-guidelines/README.zh-CN.md at master · sparanoid/chinese-copywriting-guidelines](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-CN.md) > 空格：「有研究顯示，打字的時候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會在 34 歲的時候跟自己不愛的人結婚，而其余三成的人最后只能把遺產留給自己的貓。 畢竟愛情跟書寫都需要適時地留白。 > 作為一名工程師，最被低估的技能是記錄。說真的，如果有人可以教我怎么寫文檔，我會付錢，也許是 1000 美元。 —— [程序員的酒后真言 - 阮一峰的網絡日志](https://www.ruanyifeng.com/blog/2021/06/drunk-post-of-a-programmer.html) [訪談：TC無處不在，只是我們沒有發覺 | 技術傳播](https://mp.weixin.qq.com/s?__biz=MzU3OTM4OTkzNQ%3D%3D&chksm=fd679443ca101d556b02edfe5725d31beed93704431a2a74f067ce1fac0db65a2e693e5396bd&idx=1&mid=2247484611&scene=21&sn=c49b54711d04962ca885fbae709cd974#wechat_redirect) * * * * * last update：2020-06-20 18:53:12