Rust中的高吞吐量流處理
作者 | Noz編譯 | 王瑞平本篇文章主要介紹了Rust中流處理的概念、方法和優化。作者不僅介紹了流處理的基本概念以及Rust中常用的流處理庫，還使用這些庫實現了一個流處理程序
作者 | 蔡正鋒
軟件開發中，為你的軟件系統編寫文檔并不是一件新鮮的事情。幾乎所有人都明白這樣的道理：
你的軟件產品如何優秀對用戶來說并不是最重要的，因為你的文檔如果不夠優秀，用戶不會使用它！即便用戶在某些情況下不得不使用你的產品，沒有好的文檔，用戶無法高效使用或者以錯誤的方式使用你的產品。
不幸的是，鮮少能見到關于如何正確組織技術文檔的實踐及方法論。團隊工作中，編寫文檔仍面臨挑戰。
編寫技術文檔這個任務看起來總是：優先級不夠高，特別花時間并且沒有立竿見影的正反饋！于是文檔編寫被一推再推，直至在某些時刻不得不做，比如新人要上項目了，我的開源產品要發布了，才震驚地發現我竟沒有文檔。文檔最后被隨意編寫，以至于完成后就被徹底忽視。隨著系統的演進，這些文檔慢慢脫節，變成謊言！這個論斷乍一看如此地荒謬，可是卻在我身邊常常發生。
如同代碼編寫一樣，混亂的結構是相當致命的。我們能使用類似于technical-writing-template這樣，基于模板約定的方式使得單篇文章的質量達到一定的水準。然而在復雜的軟件系統中，高質量的單篇顯然是杯水車薪的。事實上，眾多優秀的軟件產品它們基本都具備恰到好處的文檔，清晰的結構使得初學者和長期用戶讀起來都毫不費力。我以為，未能使文檔免于混亂的原因有以下幾點：
通過觀察優秀技術文檔的組織形式，諸如unix manual、Spring boot或者React，你會發現它們都是結構化的。主要使用方式是按照索引查閱感興趣的內容。
通常，所謂編寫技術文檔，基本意味著編寫類似的結構化文檔。結構化文檔不僅僅是當前最為主流的文檔組織方式，在可預見的未來也會如此。
保持清晰的結構絕非易事，筆者深感幸運能夠看到一種確保正確生成結構化文檔的模式：文檔象限。
在一個坐標系下，劃分象限的兩條軸描述了文檔所具有的屬性，橫軸描述文檔的使用場景是偏于工作的還是偏于學習的，縱軸描述文檔是偏于理論的還是偏于實踐的。這四個象限分別是tutorials，how-to guides，reference和explanation：
圖片
圖片
文檔象限將其內容呈現方式劃定了明確的邊界，讓文檔看起來簡單明了，更適合對外輸出，幫助用戶快速上手。
結構化文檔之外似乎還存在另一種文檔組織方式：圖譜化，并且初具影響力。很多時候，為了保持文章的簡潔和內聚，我喜歡使用鏈接文字將一個相關概念指向別處。一旦順著鏈接深入幾層，就會發現文檔所承載的知識很快組成一張大網。知識圖譜一詞簡直恰如其分。自2012年谷歌知識圖譜發布以來，知識圖譜的主要用武之地仍在搜索引擎，文獻檢索領域。有諸如logseq這樣的產品另辟蹊徑，強化知識之間的鏈接，以圖譜化的方式組織文檔。其主要使用方式是關鍵字檢索加上相關內容（linked reference）的跳轉。
在使用logseq的過程中，我發現這種方式更契合人類在大腦中構建的知識模型，有利于深刻又全面地理解問題。這與盧曼的《卡片筆記寫作法》有異曲同工之妙。
筆者以為，圖譜化的文檔組織方式在團隊中更適合知識的生產和管理，即作為團隊的知識庫。原因與其主要使用方式有關。盡管我認為關鍵字檢索不失為一種高效的方式，但是給新用戶的檢索能力提出了挑戰。
當你開始著手構建文檔的時候，即便不作任何考量，也要借助一些文檔工具甚至協作平臺來保存你編寫的文檔。筆者了解到一些常用的文檔工具：
文檔生成工具：
文檔托管與協同：
圖譜化文檔工具：
了解到這些文檔構建方式和工具有什么用呢？這個世界大概不存在一個完美的軟件工具或者系統使得所有的個性化需求都被滿足。當你為了協同編輯選擇了google doc，將不得不面對大量的樣式調整工作。當你使用logseq作為團隊內部的知識庫，其特有的文檔標記格式使其難以遷移到其他的工具里。這真讓人沮喪！于是乎，構建文檔也要進行類似技術選型的工作，確定一個合適的方案。這意味著要在艱難的權衡之下，選擇能滿足需求的方案，其優點仍令人振奮，其缺點還可以忍受。
值得注意的是，具備能寫文檔這樣的功能并非唯一的需求，選擇方案時我們似乎更看重功能以外的重要特性。沒錯，文檔構建也該滿足可預見的非功能性需求：
利用文檔象限組織內容，利用Github等托管平臺保存，sphinx將其生成為電子書發布，或者生成HTML進行私有化部署。
(1) 優點
(2) 缺點
:memo: Note: 這里有一個How-to guide: 于sphinx上實踐文檔象限
使用loqseq作為知識庫，利用Github等托管平臺保存文檔
(1) 優點
(2) 缺點
(1) 優點
(2) 缺點
慎重地審視這些方案各自的優缺點后，我發現采用結構化的文檔組織方式時，文檔象限總是有用武之地，似乎能夠保證我們生成“不太壞”的文檔。同時，筆者建議慎重選擇圖譜化文檔，你可能并沒有做好因文檔改變自己工作習慣的準備，你可能還需要同時維護一份結構化文檔。
本文鏈接：http://www.tebozhan.com/showinfo-26-6163-0.html如何編寫技術文檔？
聲明：本網頁內容旨在傳播知識，若有侵權等問題請及時與本網聯系，我們將在第一時間刪除處理。郵件：2376512515@qq.com
下一篇： 基于靜態編譯構建微服務應用
Copyright ? 2016-2023 天津谷騏科技有限公司 版權所有 sitemap.xml
違法及侵權請聯系：2376512515@qq.com 津ICP備18001702號
津公網安備 12010102000574號