如何編寫一篇好的技術文章

吾輩的博客原文地址是 https://blog.rxliuli.com/p/3f...

場景

人的目標老是追求「優越性」，是要擺脫自卑感以求獲得優越感。

如今網絡上已經有不少寫做平臺了，讓咱們數數: 靜態/動態博客（Hexo/WordPress），SegmentFault 專欄，簡書，掘金，CSDN 博客。然而寫做平臺不少，願意寫做的人也不少，那麼是否意味着咱們就更容易獲取知識了呢？其實並非，緣由在於不少人寫做只是跟風，以爲很酷，因此用 hexo/hugo + github pages 建了靜態站點發了一篇 hello world 以後就沒有下文了。這種暫且按下不表，吾輩主要想說的是另外一種：爲了寫做（積分）而寫做，徹底不用心，只是簡單的把概念複製了一下，甚至直接抄襲別人的文章，不註明來源，並且沒有嘗試過文章作法的人。

這裏強烈批評一下 CSDN 博客，雖然也有一些優質的博客，但更多的是直接 抄襲的文章，並且大多數都存在問題，實在使人深痛惡絕。甚至於，有人專門寫了油猴腳本 google 百度搜索屏蔽 CSDN 用來屏蔽它，糟糕程度可見一斑。

思考

那麼，真的想要開始寫做，想要把本身的知識、感觸和經驗分享給其餘人的話，有沒有什麼寫做的技巧，或者說遵循的規則呢？下面是吾輩寫做至今以來的一些經驗，但願能幫到真心想要寫做的人。

重點

• 是什麼？
• 怎麼作？
• 在哪裏用？

細節

• 排版樣式
• 插圖
• 錯別字
• 轉發文章

重點

若是要寫一個技術文檔，那麼有三點是必需要注意的。

• 是什麼？
  能夠是技術的一些簡單介紹，或是在什麼場景下會遇到這種問題，也能夠是爲何要寫這篇文章。就像吾輩，基本上每篇文章的正文都會有一個場景段落，用來介紹吾輩爲何寫這篇文章，以及對涉及問題的介紹（吐槽 #打）。
• 怎麼作？
  正確的描述具體如何使用，或是如何使用代碼實現功能/修復錯誤。例如介紹 JavaScript Array 的文章，那就須要告訴讀者如何使用常見的 API，例如 forEach, filter, map, reduce 這些函數，如何的使用它們，給出一些具體可運行的示例，若是有你以爲讀者會難以理解的部分，更應該詳細解釋，並配上代碼示例。
• 在哪裏用？
  寫做最有可能漏掉的部分，但倒是最重要的。若是文章只是單純羅列了一堆概念和代碼，卻不告訴讀者在什麼場景下才會用到，那麼這隻會是至關糟糕的文章，還不如去看官方文檔（大部分文檔都是告訴怎麼作而不告訴在哪裏用，尤爲是某些 HTML/CSS 書籍，簡直是把 MDN 的文檔抄了一遍），至少還準確一些。

細節

• 排版樣式
  讀者進入網頁以後，第一眼看到的絕對不是具體的內容，而是網頁的排版大體是什麼樣子的，這點在讀者閱讀時可以清晰的感覺出來。就像人的外貌，在開口前讀者便能藉此看出大概（所謂以貌取人）。即使可能在讀者繼續閱讀內容而扭轉形象，但更有多是讀者直接點 X 關閉網頁，而且留下了很差的印象。
  因此排版真的很重要，下面提供吾輩的幾條經驗:

  • 不要是純 TXT 文本格式（大忌）
  • 使用代碼塊包裹代碼片斷，不要直接和普通文本同樣，沒有語法高亮看代碼會死人的。
  • 合理使用標題。標題應該是逐級減少，而不該該出現一級標題，而後馬上就是三級標題，中間必定且必須有一個二級標題。
  • 文章中的連接應該是可點擊的，而且最好引用一些比較官方的內容（MDN，Wiki）。
  • 錯誤示例: https://blog.csdn.net/xlxxcc/...

• 插圖
  若是說排版樣式是外貌，那圖片就像人的衣服同樣，能爲文章錦上添花。更況且還有 一圖勝千言 的說法，能夠避免讀者在閱讀時感到無聊。像是若是有流程圖/原理圖/時序圖這些，將會顯著的提升文章的層次。

  附: 畫圖真的很花時間，若是有圖片的話，說明做者是真的用心在寫文章。（通常是大佬纔會作，吾輩不是大佬，因此通常不會畫圖 #笑哭）

• 錯別字
  但凡寫做，若是有人說本身沒寫過錯別字，吾輩是第一個不信的。人非聖賢，孰能無過。寫做時出現錯別字是很正常的，但因爲人類自己的緣由（參考 查出本身的錯別字，爲何這麼難？），因此想要檢查是比較困難的 -- 但並非毫無辦法，咱們在文章發佈後，在網絡上再次查看文章，會比在編輯器中更容易察覺到文章中的問題，這其中固然包含錯別字。
• 轉發文章
  當咱們在網絡上看到別人的文章，以爲寫得很好，因而轉發了文章想讓更多人看到。但在轉發以前，最好先詢問一下原做者的意願（通常是容許署名轉載的），並且必需要在顯眼的位置（文章頂部或尾部，通常最好是頂部）放置原文的連接，以使讀者可以找到原做者。

總結

上面說了這麼多，還有最後一句話要送給你們: 保持做者這個稱呼的基本水平和對讀者的基本尊重。