如何寫出一篇高質量的技術分享文件

自己也寫技術分享文章，也經常看別人的分享文章，本篇就簡單梳理梳理個人的一些看法，希望能給一些準備寫技術分享的同學一點幫助。

優先確定技術文章面向的受眾 。 是初級、中級還是高階、資深人員，面向不同的人群，所需措辭也不同，同一個詞因人不同的知識結構會導致不同的解讀，所以儘量減少這種不必要的消化損耗。文章真正被閱讀的受眾，這個是無法控制的，事先定好基調就比較容易把握文章深度，淺顯易懂最好不過了。

其次要 考慮到技術應用的上下文環境 ，這個要交待清楚，能解決什麼問題，適用在什麼場景下，如果能把類似的解決方案順便提一下，更能閱讀受眾的知識面。

多使用圖表。 一圖勝千言，對於晦澀的演算法、流程、結構等，一張漂亮的圖，那怕是草圖，也能使讀者很容易走近文章的世界，吸收文章的精華內容。相比滿屏的文字，圖表會花費較少的時間被閱讀接受。

新名詞的使用要引出簡要的註釋，便於讀者消化吸引。 由於 知識詛咒 的存在(通俗地說，就是一旦你知道了一個資訊（學會了一樣東西），你就很難想象你不知道該資訊（沒學會該東西）的情景。)，總會有一些我們常用但別人卻不懂的名詞存在，這會加大閱讀的難度，也會給讀者一個放棄文章不再閱讀的選擇。

如果我在一篇文章中碰到了一個新名詞，一般來講我會去檢索弄懂，如果另外的文章中還有，則會引起一連串的檢索，那本來我要讀的那篇文章就會越為越遠離我的視線。當然，我沒讀完的有興趣文章，一般也不會關閉，至到把所有新名詞弄懂。

要不要貼程式碼。 不少同學的部落格裡出現大篇的詳細程式碼，但讀者去用的話，有時候完全不能執行，導致錯誤百出。自己的環境裡上下文裡有的東西，別人不一定有。

如果你決定貼程式碼，就要順便把程式碼中的引用一併講清楚，這對有幫助的人來講，將會對你感激不盡。（一般有現成的程式碼，大家普遍喜歡直接Copy，而不是自己消化後自己寫一篇，這不符合Ctrl+c/Ctrl+V編碼的風格）當然有些讀者會要求人，為什麼不這樣那樣，這是當事人涉及的另外一回事了。

如果不貼具體程式碼，可以採用虛擬碼替代。即講清楚了實現的邏輯，也避免了讀者直接copy程式碼導致的各種問題。

文章的延伸性 。 一篇好文，讀完酣暢淋漓，受益匪淺。不過有時候總有意猶未盡的感受，這個時候如果能適當的擴充套件一下，引申出更多的方向

題圖 from unsplash

說完裡子，再說面子， 一篇 條理清晰、結構融洽的文章讀起來總能事半功倍 ，富文字編輯也好，Markdown編輯也好，較適當的內容以適當的格式表現出來，文字大小適中，段落控制得當等，多寫幾次基本就輕車熟路了。

行文的可讀性 。 有些文章比較晦澀，但通過形象的比喻，能夠助於讀者更好的理解接受，遠比一篇全是生硬的術語堆積起來的文章更加能夠吸引人的。原理總是枯燥的，但小故事永遠總會吸引人的。

雖然這篇文章質量高在讀者看來高低未可知，但是我也總希望別人寫的文章能達到以上的條件，一同努力。