1. 當(dāng)“參考資源”成為章節(jié)標(biāo)題時(shí)它到底在解決什么問(wèn)題翻技術(shù)書翻到最后一章看到“參考資源”四個(gè)字很多人的第一反應(yīng)是“這章可以跳過(guò)”。我早年也這么干過(guò)直到有次排查一個(gè)內(nèi)存泄漏問(wèn)題翻遍前三十一章都沒(méi)找到答案最后在參考資源里發(fā)現(xiàn)作者留了一個(gè)內(nèi)存分析工具的鏈接和一段配置說(shuō)明五分鐘解決問(wèn)題。從那以后我養(yǎng)成了一個(gè)習(xí)慣拿到任何一本技術(shù)書或者一份項(xiàng)目文檔先翻到參考資源那一章掃一眼判斷這個(gè)作者是不是真的在一線干過(guò)活?！暗?2章參考資源”這個(gè)標(biāo)題看起來(lái)平平無(wú)奇但它背后承載的東西遠(yuǎn)比表面復(fù)雜。它不是一個(gè)簡(jiǎn)單的“參考文獻(xiàn)列表”而是一個(gè)項(xiàng)目或一本書的知識(shí)收口。寫這一章的人需要把前面三十一章里所有提到過(guò)的工具、庫(kù)、標(biāo)準(zhǔn)、社區(qū)、延伸閱讀材料按照某種邏輯重新組織一遍讓讀者在讀完正文之后有一個(gè)清晰的“下一步該去哪里”的路線圖。這件事做得好不好直接決定了讀者能不能從“看懂了”過(guò)渡到“會(huì)用了”。這一章的核心價(jià)值在于三個(gè)層面。第一是可追溯性正文里提到的每一個(gè)技術(shù)決策、每一個(gè)參數(shù)取值、每一個(gè)架構(gòu)選擇讀者如果想知道“憑什么”參考資源就是溯源入口。第二是可擴(kuò)展性正文受限于篇幅不可能把所有細(xì)節(jié)展開(kāi)參考資源承擔(dān)了“知識(shí)延展接口”的角色。第三是可驗(yàn)證性讀者可以順著參考資源里的工具和數(shù)據(jù)集自己復(fù)現(xiàn)正文中的實(shí)驗(yàn)或效果這是技術(shù)內(nèi)容可信度的基石。適合讀這一章的人不是剛?cè)腴T的新手而是已經(jīng)跟著正文走了一遍、手里有具體問(wèn)題需要深入的人。如果你正在做一個(gè)類似的項(xiàng)目卡在某個(gè)環(huán)節(jié)正文給的是“怎么做”參考資源給的是“為什么這么做”和“還能怎么做”。所以這一章的正確打開(kāi)方式不是從頭讀到尾而是帶著問(wèn)題去查、去跳轉(zhuǎn)、去驗(yàn)證。我見(jiàn)過(guò)太多項(xiàng)目文檔把參考資源寫成了一堆死鏈接的堆砌也見(jiàn)過(guò)一些優(yōu)秀的項(xiàng)目把這一章做成了整個(gè)文檔里訪問(wèn)量最高的部分。差別就在于作者有沒(méi)有站在“讀者接下來(lái)要干什么”的角度去組織內(nèi)容。下面我就按自己的經(jīng)驗(yàn)把這一章拆開(kāi)來(lái)講從結(jié)構(gòu)設(shè)計(jì)到內(nèi)容篩選再到實(shí)際使用中的坑全部過(guò)一遍。2. 參考資源的四種組織邏輯與各自的適用場(chǎng)景2.1 按知識(shí)層級(jí)組織從入門到精通的階梯這是最常見(jiàn)也最實(shí)用的一種組織方式。作者把參考資源分成幾個(gè)層級(jí)比如“基礎(chǔ)概念補(bǔ)充”“進(jìn)階原理深入”“實(shí)戰(zhàn)案例參考”“社區(qū)與持續(xù)更新”。每一層對(duì)應(yīng)讀者不同的需求階段。我做過(guò)一個(gè)圖像處理相關(guān)的項(xiàng)目參考資源那一章就是按這個(gè)邏輯寫的。基礎(chǔ)層放的是色彩空間轉(zhuǎn)換的數(shù)學(xué)推導(dǎo)文檔進(jìn)階層放的是卷積神經(jīng)網(wǎng)絡(luò)在圖像去噪中的論文實(shí)戰(zhàn)層放的是幾個(gè)開(kāi)源數(shù)據(jù)集和預(yù)訓(xùn)練模型的下載地址社區(qū)層放的是幾個(gè)活躍的技術(shù)論壇和郵件列表。這種組織方式的好處是讀者不需要自己判斷“我現(xiàn)在該看什么”作者已經(jīng)幫你分好了。但這里有個(gè)坑層級(jí)劃分不能太細(xì)三層到四層就夠了。我見(jiàn)過(guò)一個(gè)項(xiàng)目分了七層從“科普讀物”到“前沿論文”再到“標(biāo)準(zhǔn)文檔”讀者看到第三層就暈了。層級(jí)太多等于沒(méi)有層級(jí)因?yàn)樽x者記不住每一層放的是什么。2.2 按工具鏈組織圍繞核心工作流串聯(lián)如果你的項(xiàng)目涉及一套完整的工作流比如數(shù)據(jù)采集、清洗、建模、部署、監(jiān)控那參考資源按工具鏈來(lái)組織會(huì)更自然。每個(gè)環(huán)節(jié)下列出對(duì)應(yīng)的工具、庫(kù)、配置文檔和最佳實(shí)踐。這種組織方式的優(yōu)勢(shì)在于場(chǎng)景感強(qiáng)。讀者在哪個(gè)環(huán)節(jié)卡住了直接跳到對(duì)應(yīng)的工具列表就行。比如你在模型部署環(huán)節(jié)遇到性能瓶頸翻到“部署與優(yōu)化”那一節(jié)里面列了推理引擎、量化工具、性能分析器的鏈接比你去搜索引擎里大海撈針高效得多。我個(gè)人的經(jīng)驗(yàn)是按工具鏈組織時(shí)每個(gè)工具后面最好加一句“什么時(shí)候用它”。比如“某推理引擎適合需要低延遲的場(chǎng)景配置復(fù)雜度中等”這樣讀者不用點(diǎn)進(jìn)去就能判斷要不要深入。這句話看起來(lái)簡(jiǎn)單但寫的時(shí)候需要作者真的用過(guò)這些工具否則寫出來(lái)的推薦語(yǔ)就是廢話。2.3 按問(wèn)題域組織以“癥狀”為索引的速查表這種組織方式比較少見(jiàn)但我覺(jué)得對(duì)實(shí)戰(zhàn)型項(xiàng)目特別有用。作者不按知識(shí)體系或工具鏈來(lái)分而是按“你遇到了什么問(wèn)題”來(lái)分。比如“訓(xùn)練不收斂怎么辦”“推理速度慢怎么辦”“內(nèi)存占用過(guò)高怎么辦”每個(gè)問(wèn)題下面列出相關(guān)的參考資源。這本質(zhì)上是一個(gè)故障排查索引。它的價(jià)值在于讀者不需要知道問(wèn)題出在哪個(gè)環(huán)節(jié)只需要描述癥狀就能找到對(duì)應(yīng)的資源。我參與過(guò)一個(gè)跨平臺(tái)系統(tǒng)的開(kāi)發(fā)參考資源那一章就是按這個(gè)邏輯寫的后來(lái)發(fā)現(xiàn)這一章的訪問(wèn)量是其他章節(jié)的好幾倍因?yàn)榇蠹叶际窃谟龅絾?wèn)題的時(shí)候才去翻文檔。寫這種組織方式的參考資源難點(diǎn)在于問(wèn)題描述要足夠具體?！靶阅軉?wèn)題”太寬泛“推理延遲超過(guò)200毫秒”就具體得多。問(wèn)題越具體讀者越容易對(duì)號(hào)入座。2.4 按更新頻率組織區(qū)分“穩(wěn)定層”和“活躍層”技術(shù)內(nèi)容有一個(gè)天然的矛盾核心原理相對(duì)穩(wěn)定但工具和庫(kù)的版本更新很快。參考資源如果混在一起讀者分不清哪些是“可以放心引用的經(jīng)典”哪些是“可能下個(gè)月就過(guò)時(shí)的鏈接”。我的做法是把參考資源分成兩層。穩(wěn)定層放的是教科書、經(jīng)典論文、標(biāo)準(zhǔn)文檔、數(shù)學(xué)推導(dǎo)這些東西五年十年不會(huì)變?；钴S層放的是開(kāi)源項(xiàng)目、社區(qū)討論、版本更新日志、在線課程這些東西需要讀者自己判斷時(shí)效性。每一層前面加一句說(shuō)明比如“以下資源的核心內(nèi)容長(zhǎng)期有效”和“以下資源請(qǐng)關(guān)注更新日期建議優(yōu)先查看最近兩年的內(nèi)容”。這種組織方式對(duì)讀者的幫助是隱性的但很重要。它教會(huì)讀者一個(gè)判斷標(biāo)準(zhǔn)不是所有參考資源都同等可靠你需要根據(jù)資源的類型來(lái)判斷它的時(shí)效性和權(quán)威性。3. 篩選參考資源時(shí)我在意的三個(gè)硬指標(biāo)3.1 可訪問(wèn)性鏈接會(huì)死但知識(shí)不會(huì)參考資源最尷尬的情況就是鏈接失效。我統(tǒng)計(jì)過(guò)自己收藏的技術(shù)文檔三年后還能正常訪問(wèn)的不到六成。所以我在篩選參考資源時(shí)第一條標(biāo)準(zhǔn)就是可訪問(wèn)性。具體怎么做優(yōu)先選擇有穩(wěn)定域名的官方文檔而不是個(gè)人博客的臨時(shí)鏈接。如果必須引用個(gè)人博客我會(huì)同時(shí)給出文章標(biāo)題和作者名這樣即使鏈接失效讀者也能通過(guò)搜索引擎找到轉(zhuǎn)載或存檔。對(duì)于開(kāi)源項(xiàng)目?jī)?yōu)先給出項(xiàng)目主頁(yè)而不是某個(gè)具體文件的鏈接因?yàn)槲募窂娇赡軙?huì)變。還有一個(gè)技巧對(duì)于特別重要的參考資源我會(huì)在正文里直接給出核心內(nèi)容摘要而不是只丟一個(gè)鏈接。這樣即使鏈接失效讀者至少知道這個(gè)資源講了什么值不值得去找。比如“某篇論文提出了用注意力機(jī)制優(yōu)化特征融合的方法核心思想是對(duì)不同尺度的特征賦予可學(xué)習(xí)的權(quán)重”這句話本身就是信息鏈接只是補(bǔ)充。3.2 權(quán)威性誰(shuí)寫的比寫什么更重要技術(shù)內(nèi)容的權(quán)威性判斷我一般看三個(gè)維度作者背景、發(fā)布平臺(tái)、引用次數(shù)。作者背景不是看頭銜而是看他在這個(gè)領(lǐng)域有沒(méi)有實(shí)際產(chǎn)出。發(fā)布平臺(tái)看的是有沒(méi)有同行評(píng)審或社區(qū)審核機(jī)制。引用次數(shù)看的是這篇內(nèi)容有沒(méi)有被其他從業(yè)者認(rèn)可。但權(quán)威性不是絕對(duì)的。有些前沿領(lǐng)域最新的實(shí)踐可能來(lái)自一線工程師的博客而不是學(xué)術(shù)論文。這時(shí)候我會(huì)在參考資源里標(biāo)注“以下內(nèi)容來(lái)自工業(yè)界實(shí)踐未經(jīng)學(xué)術(shù)評(píng)審但在一線項(xiàng)目中驗(yàn)證有效”。這種標(biāo)注本身就是一種價(jià)值判斷幫助讀者建立預(yù)期。我踩過(guò)的一個(gè)坑是早期做項(xiàng)目時(shí)盲目引用了一篇看起來(lái)很高深的論文后來(lái)發(fā)現(xiàn)里面的實(shí)驗(yàn)條件和我實(shí)際場(chǎng)景差別很大方法根本沒(méi)法直接用。從那以后我在參考資源里會(huì)加一句“適用場(chǎng)景”說(shuō)明比如“該方法在數(shù)據(jù)量充足的情況下效果顯著小樣本場(chǎng)景需謹(jǐn)慎參考”。3.3 可操作性能不能直接上手參考資源的價(jià)值最終要落到“能不能用”上。我判斷一個(gè)資源是否可操作看它有沒(méi)有給出完整的步驟、配置、參數(shù)和預(yù)期結(jié)果。如果只是一段原理描述沒(méi)有實(shí)操指引那它更適合放在“延伸閱讀”而不是“參考資源”里。舉個(gè)例子同樣是介紹一個(gè)數(shù)據(jù)處理庫(kù)A資源只說(shuō)了“這個(gè)庫(kù)可以高效處理大規(guī)模數(shù)據(jù)”B資源給出了安裝命令、核心API的調(diào)用示例、常見(jiàn)參數(shù)的含義和取值建議、以及一個(gè)完整的處理流程。B資源才是合格的參考資源因?yàn)樗屪x者能直接動(dòng)手。我在整理參考資源時(shí)會(huì)刻意區(qū)分“讀”和“做”兩類資源。讀的資源放在前面做的資源放在后面并且給做的資源加上“預(yù)計(jì)上手時(shí)間”的標(biāo)注。比如“預(yù)計(jì)30分鐘可跑通示例”這樣讀者可以根據(jù)自己的時(shí)間安排選擇。4. 把參考資源用起來(lái)的實(shí)操方法從查到用再到改4.1 建立自己的資源索引不要只收藏要加工很多人看到好的參考資源第一反應(yīng)是收藏。但收藏不等于擁有更不等于會(huì)用。我的做法是建立一個(gè)自己的資源索引每收錄一個(gè)資源就寫三句話這個(gè)資源解決什么問(wèn)題、核心方法是什么、我打算怎么用。這個(gè)索引不需要很復(fù)雜一個(gè)Markdown文件就夠了。關(guān)鍵是加工的過(guò)程。你在寫這三句話的時(shí)候?qū)嶋H上是在用自己的語(yǔ)言重新理解這個(gè)資源這個(gè)動(dòng)作比單純收藏有價(jià)值得多。我現(xiàn)在的索引里有三百多條記錄每次做新項(xiàng)目先搜一遍索引能省掉大量重復(fù)搜索的時(shí)間。索引的維護(hù)也有技巧。我會(huì)給每條記錄打上標(biāo)簽比如“圖像處理”“性能優(yōu)化”“數(shù)據(jù)可視化”這樣搜索的時(shí)候可以按標(biāo)簽過(guò)濾。標(biāo)簽不要太多十個(gè)以內(nèi)就夠了太多反而增加維護(hù)成本。4.2 驗(yàn)證性閱讀帶著問(wèn)題去查而不是從頭讀到尾參考資源不是用來(lái)通讀的是用來(lái)查的。我讀參考資源的典型流程是先看目錄或摘要判斷這個(gè)資源和我當(dāng)前問(wèn)題的相關(guān)度然后跳到最相關(guān)的部分快速掃一遍如果確實(shí)有用再回頭細(xì)讀。這個(gè)過(guò)程中我會(huì)帶著三個(gè)問(wèn)題這個(gè)資源的核心結(jié)論是什么它的前提條件是什么在我的場(chǎng)景下適用嗎第三個(gè)問(wèn)題最重要因?yàn)楹芏噘Y源在特定條件下有效換個(gè)場(chǎng)景就不行了。比如一個(gè)優(yōu)化方法在GPU環(huán)境下效果顯著但你的部署環(huán)境只有CPU那就需要找替代方案。驗(yàn)證性閱讀的另一個(gè)好處是建立批判性思維。你不會(huì)盲目相信任何一個(gè)資源而是會(huì)主動(dòng)判斷它的適用范圍和局限性。這種判斷力是區(qū)分新手和老手的重要標(biāo)志。4.3 二次加工把參考資源變成自己的知識(shí)參考資源的最高境界是把它變成你自己的東西。具體怎么做我的方法是改寫和重組。讀完一個(gè)資源后我會(huì)用自己的話把核心內(nèi)容寫一遍然后把它和我已有的知識(shí)關(guān)聯(lián)起來(lái)。比如我讀了一篇關(guān)于模型壓縮的論文我會(huì)寫一段筆記“這篇論文提出了通道剪枝的方法核心思想是去掉對(duì)輸出影響小的通道。這和我之前了解的權(quán)重剪枝有什么區(qū)別通道剪枝是結(jié)構(gòu)化剪枝可以直接減少計(jì)算量權(quán)重剪枝是非結(jié)構(gòu)化剪枝需要專門的硬件支持才能加速。在我的項(xiàng)目里因?yàn)椴渴瓠h(huán)境是通用CPU所以通道剪枝更合適?！边@段筆記就是二次加工的產(chǎn)物。它不只是復(fù)述論文內(nèi)容而是把新知識(shí)和舊知識(shí)連接起來(lái)形成了一個(gè)可以指導(dǎo)決策的判斷。這樣的筆記才是真正屬于你的參考資源。5. 那些年我在參考資源上踩過(guò)的坑5.1 鏈接失效最容易被忽視的維護(hù)成本我做過(guò)一個(gè)內(nèi)部技術(shù)文檔參考資源那一章列了五十多個(gè)鏈接。半年后有人反饋說(shuō)一半的鏈接打不開(kāi)。我一個(gè)個(gè)檢查發(fā)現(xiàn)有些是域名過(guò)期有些是頁(yè)面路徑變更還有些是內(nèi)容被刪除了。修復(fù)這些鏈接花了我整整一個(gè)下午。從那以后我養(yǎng)成了兩個(gè)習(xí)慣。第一參考資源里的鏈接優(yōu)先選擇有穩(wěn)定維護(hù)的官方文檔而不是個(gè)人博客或臨時(shí)頁(yè)面。第二對(duì)于特別重要的資源我會(huì)在鏈接后面加一個(gè)“存檔”按鈕指向網(wǎng)頁(yè)存檔服務(wù)的快照。這樣即使原鏈接失效讀者也能看到歷史版本。還有一個(gè)更徹底的做法對(duì)于核心參考資源直接把關(guān)鍵內(nèi)容摘錄到文檔里鏈接只作為出處標(biāo)注。這樣做的好處是文檔自包含不依賴外部鏈接的存活。缺點(diǎn)是會(huì)增加文檔篇幅需要權(quán)衡。5.2 版本漂移你引用的版本和讀者用的版本可能不一樣技術(shù)文檔的參考資源經(jīng)常涉及具體的軟件版本。我寫文檔的時(shí)候用的是某個(gè)庫(kù)的2.3版本讀者看到的時(shí)候可能已經(jīng)出到3.0了API變了配置方式也變了參考資源里的示例代碼直接報(bào)錯(cuò)。解決這個(gè)問(wèn)題的辦法是版本鎖定。在參考資源里明確標(biāo)注“以下內(nèi)容基于某庫(kù)2.3版本3.0版本的變化請(qǐng)參考遷移指南”。如果可能的話給出具體的版本號(hào)和下載鏈接而不是籠統(tǒng)地說(shuō)“最新版本”。對(duì)于開(kāi)源項(xiàng)目我還會(huì)關(guān)注它的發(fā)布節(jié)奏。如果一個(gè)項(xiàng)目半年才發(fā)一次版本那版本漂移的風(fēng)險(xiǎn)就小如果一個(gè)月發(fā)三次那參考資源就需要更頻繁地更新。這個(gè)判斷會(huì)影響我在參考資源里投入的維護(hù)精力。5.3 信息過(guò)載參考資源不是越多越好我見(jiàn)過(guò)一個(gè)項(xiàng)目的參考資源列了兩百多條從學(xué)術(shù)論文到博客文章到視頻教程應(yīng)有盡有。但讀者反饋說(shuō)“不知道從哪看起”。這就是典型的信息過(guò)載。參考資源的數(shù)量和質(zhì)量需要平衡。我的經(jīng)驗(yàn)是核心資源控制在十條以內(nèi)延伸資源不超過(guò)三十條。核心資源是“必讀”延伸資源是“選讀”。每一類下面按重要程度排序最重要的放在最前面。還有一個(gè)技巧給每條資源加一個(gè)“一句話推薦語(yǔ)”。比如“如果你想深入理解X的原理這篇論文是最系統(tǒng)的”“如果你只想快速上手這個(gè)教程三十分鐘就能跑通”。推薦語(yǔ)幫助讀者快速判斷要不要點(diǎn)進(jìn)去減少?zèng)Q策成本。6. 從參考資源反推項(xiàng)目質(zhì)量一個(gè)實(shí)用的判斷方法6.1 參考資源的組織方式暴露了作者的思維方式我判斷一個(gè)項(xiàng)目文檔的質(zhì)量有一個(gè)快捷方法直接翻到參考資源那一章。如果這一章只是零散鏈接的堆砌沒(méi)有分類、沒(méi)有說(shuō)明、沒(méi)有更新日期那這個(gè)文檔的其他部分大概率也是粗制濫造的。如果這一章結(jié)構(gòu)清晰、說(shuō)明到位、有版本標(biāo)注那這個(gè)項(xiàng)目的整體質(zhì)量通常不會(huì)差。背后的邏輯很簡(jiǎn)單參考資源是文檔的“收口”它需要作者對(duì)全部?jī)?nèi)容有全局把握才能把散落在各處的引用整理成有邏輯的結(jié)構(gòu)。一個(gè)連參考資源都懶得整理的作者很難相信他在正文里會(huì)認(rèn)真對(duì)待每一個(gè)技術(shù)細(xì)節(jié)。6.2 看作者推薦了什么比看作者寫了什么更有信息量作者在正文里寫的內(nèi)容是經(jīng)過(guò)篩選和組織的你看到的是他想讓你看到的東西。但參考資源不一樣它暴露了作者的知識(shí)來(lái)源和判斷標(biāo)準(zhǔn)。一個(gè)推薦了高質(zhì)量論文和官方文檔的作者和一個(gè)只推薦了自己博客和營(yíng)銷文章的作者專業(yè)度差距一目了然。我特別關(guān)注作者有沒(méi)有推薦“反面教材”。比如“這個(gè)方案看起來(lái)很美但在我們的場(chǎng)景下失敗了原因如下”。這種內(nèi)容在正文里可能不方便寫但在參考資源里可以坦誠(chéng)地分享。愿意分享失敗經(jīng)驗(yàn)的作者通常更值得信任。6.3 參考資源的更新頻率反映了項(xiàng)目的活躍度如果一個(gè)項(xiàng)目的參考資源里最新的鏈接是三年前的那這個(gè)項(xiàng)目大概率已經(jīng)停止維護(hù)了。反過(guò)來(lái)如果參考資源里有最近半年的更新說(shuō)明作者還在持續(xù)關(guān)注這個(gè)領(lǐng)域項(xiàng)目也在活躍發(fā)展中。這個(gè)判斷方法對(duì)于選擇技術(shù)棧特別有用。你在選一個(gè)框架或庫(kù)的時(shí)候看看它的參考資源更新頻率就能大致判斷它的社區(qū)活躍度和長(zhǎng)期維護(hù)前景。一個(gè)連文檔都不更新的項(xiàng)目很難指望它持續(xù)修復(fù)bug和適配新環(huán)境。7. 把參考資源變成你的第二大腦參考資源這一章表面上是給讀者看的實(shí)際上也是給作者自己看的。我在整理參考資源的過(guò)程中經(jīng)常會(huì)有新的發(fā)現(xiàn)原來(lái)這兩個(gè)問(wèn)題可以用同一個(gè)方法解決原來(lái)這個(gè)工具在另一個(gè)場(chǎng)景下也適用。這種跨領(lǐng)域的連接往往能帶來(lái)意想不到的靈感。我的建議是不要等到項(xiàng)目結(jié)束才去整理參考資源。從項(xiàng)目開(kāi)始的第一天起就建立一個(gè)資源收集的習(xí)慣。每讀一篇論文、每試一個(gè)工具、每解決一個(gè)問(wèn)題就把相關(guān)的資源記錄下來(lái)寫上幾句自己的理解。等到項(xiàng)目結(jié)束的時(shí)候參考資源那一章已經(jīng)自然成型了不需要額外花時(shí)間整理。更重要的是這個(gè)習(xí)慣會(huì)讓你逐漸建立起自己的知識(shí)體系。你不再是被動(dòng)地接收信息而是主動(dòng)地篩選、加工、連接。時(shí)間長(zhǎng)了你會(huì)發(fā)現(xiàn)自己的判斷力越來(lái)越準(zhǔn)遇到新問(wèn)題的時(shí)候知道該去哪里找答案也知道哪些答案更可靠。這才是參考資源真正的價(jià)值所在。