編者按：本文作者是螞蟻集團(tuán)前端工程師依楓，梳理了一些寫(xiě)技術(shù)分享文章的要點(diǎn)，目的是為了幫助技術(shù)同學(xué)更好的編寫(xiě)技術(shù)分享文檔，歡迎一起交流～

前言

最近部門(mén)在推技術(shù)分享的沉淀，每個(gè)小組平常也會(huì)有自己的技術(shù)分享。技術(shù)同學(xué)往往最擅長(zhǎng)的是寫(xiě)代碼，我們發(fā)現(xiàn)很多同學(xué)在做技術(shù)分享的時(shí)候，容易陷入僅僅把自己做的事情羅列出來(lái)的誤區(qū)，難以收獲好的分享效果。

本文基于自己之前做技術(shù)分享的經(jīng)驗(yàn)，同時(shí)結(jié)合了組內(nèi)同學(xué)的建議，梳理了一些寫(xiě)技術(shù)分享文章的要點(diǎn)，目的是為了幫助技術(shù)同學(xué)更好的編寫(xiě)技術(shù)分享文檔。

明確你的分享對(duì)象和分享目的

• 明確你的分享對(duì)象：這次分享面向的是什么樣的對(duì)象？同小組的技術(shù)同事、大部門(mén)的技術(shù)同事，還是社區(qū)的技術(shù)同學(xué)？

• 明確你的分享目的：你做這次分享，目的是為了對(duì)方能夠從中收獲什么，是希望了解怎么實(shí)現(xiàn)這個(gè)技術(shù)方案？是希望能夠找到適合的場(chǎng)景去用這個(gè)方案？是啟發(fā)讀者在類似場(chǎng)景去做更好的方案設(shè)計(jì)？還是拋磚引玉希望讀者持續(xù)關(guān)注你的開(kāi)源技術(shù)棧？

大綱體現(xiàn)了你的分享思路

?? 大家可以先想一個(gè)場(chǎng)景，閱讀一本書(shū)的時(shí)候，我們會(huì)最先做什么事情：是不是會(huì)先看一看目錄，了解下這本書(shū)大致有些什么內(nèi)容、每個(gè)章節(jié)的重點(diǎn)有哪些？

技術(shù)分享文章也是一樣，讀者從標(biāo)題點(diǎn)進(jìn)來(lái)，首先需要看的這篇文章的大綱。

所以，我們作為技術(shù)文檔的編寫(xiě)者，要重視大綱，先大綱后內(nèi)容，大綱很多時(shí)候體現(xiàn)了你梳理這篇分享的思路。通過(guò)講哪些點(diǎn)可以讓讀者清楚這件事情的前因后果，每個(gè)點(diǎn)之間通過(guò)怎樣的遞進(jìn)關(guān)系可以讓讀者更好地理解？例如，技術(shù)分享文章，一般的大綱是 背景 -> 目標(biāo) -> 方案思路 -> 方案原理/細(xì)節(jié) -> 達(dá)到的效果 -> 啟發(fā) -> 致謝。

大綱梳理清楚了以后，填內(nèi)容也會(huì)變得更加容易。

先講背景和目標(biāo)

? 盡量避免上來(lái)就開(kāi)始講方案，讀者大概率是一臉懵。

? ?不妨先講講背景，你為什么要做這件事？目前業(yè)務(wù)的痛點(diǎn)是什么，現(xiàn)狀是什么，我們要怎么解決、希望達(dá)成的目標(biāo)是什么。

? 對(duì)于一些先進(jìn)性的技術(shù)方案，也需要講清楚這件事為什么是前端做的背景：哪些事情是只能前端做的，哪些事情是前后端都可以做的但是更應(yīng)該放在前端做的（講清楚利弊）。

講方案細(xì)節(jié)前先講方案整體思路

? 講方案的時(shí)候不要直接展開(kāi)細(xì)節(jié)。我們需要知道一點(diǎn)：不是所有的讀者都有技術(shù)基礎(chǔ)能夠看懂你的細(xì)節(jié)，也不是所有的讀者都對(duì)你的方案細(xì)節(jié)有興趣。

? ?先總后分，讀者需要先有一個(gè)整體的思路去引導(dǎo)，先看到全局，再到每個(gè)點(diǎn)的細(xì)節(jié)。講方案整體思路的時(shí)候，我們可以結(jié)合一些流程圖來(lái)更加直觀地表達(dá)。

講方案細(xì)節(jié)的時(shí)候結(jié)合原理和舉例

講方案細(xì)節(jié)的時(shí)候，需要結(jié)合原理和舉例。

原理是在講細(xì)節(jié)前，先讓讀者知道這個(gè)東西是什么。

舉例也很重要，說(shuō)一大堆概念、講一大段代碼，讀者可能并不能直接消化，但是，如果你結(jié)合這個(gè)場(chǎng)景舉個(gè)例子，讀者就能更容易理解了。

show 出你達(dá)到的效果

從背景到思路到細(xì)節(jié)，讀者還想要關(guān)注，這個(gè)方案，究竟有沒(méi)有達(dá)到上面的目標(biāo)？這個(gè)方案牛，它有多牛？這個(gè)方案效果究竟是啥樣的，我能不能用？

• 究竟有沒(méi)有達(dá)到上面的目標(biāo)：結(jié)合上面稱述的背景，給出實(shí)現(xiàn)的效果截圖（有對(duì)比圖更好、必要的話動(dòng)圖比靜圖更直觀）；

• 這個(gè)方案牛，它有多牛：對(duì)比已有的技術(shù)方案，改進(jìn)的點(diǎn)是什么，有沒(méi)有指標(biāo)可以量化、對(duì)比；

• 這個(gè)方案效果究竟是啥樣的，我能不能用：方案除了解這個(gè)背景的問(wèn)題，是否具有可擴(kuò)展性，哪些場(chǎng)景可以通用的可以列出來(lái)，或者一些未來(lái)的思考；

方案背后的啟發(fā)

? 不僅僅是完成了本次的技術(shù)方案，通過(guò)這次方案，給自己以及其他同學(xué)帶來(lái)了哪些啟發(fā)：

• 沉淀有哪些可借鑒復(fù)用的技術(shù)方案；

• 突破了哪些技術(shù)先進(jìn)性；

• 提升了哪些領(lǐng)域認(rèn)知；

• 抽象了哪些關(guān)于設(shè)計(jì)方案的思路。

最后的致謝

很多時(shí)候，厲害的方案都是很多人共同的智慧。過(guò)程中，如果有對(duì)你有幫助的同學(xué)，可以在文章最后列出來(lái)感謝一下 ??。相信大家也有被@過(guò)的感覺(jué)吧，感恩的心也是愉快合作的開(kāi)始。

好的，在這里我需要@一下我的同事蘇泊，感謝給大家提供的關(guān)于寫(xiě)文檔做分享的建議，一起加油，共同成長(zhǎng)。