Redmi Pad評測：紅米充滿野心的一次嘗試
從Note系列到K系列，從藍牙耳機到筆記本電腦，紅米不知不覺之間也已經形成了自己頗有競爭力的產品體系，在中端和次旗艦市場上甚至要比小米新機的表現來得更好，正所謂“大丈夫生居
作者 | 蔡正鋒
軟件開發中，為你的軟件系統編寫文檔并不是一件新鮮的事情。幾乎所有人都明白這樣的道理：
你的軟件產品如何優秀對用戶來說并不是最重要的，因為你的文檔如果不夠優秀，用戶不會使用它！即便用戶在某些情況下不得不使用你的產品，沒有好的文檔，用戶無法高效使用或者以錯誤的方式使用你的產品。
不幸的是，鮮少能見到關于如何正確組織技術文檔的實踐及方法論。團隊工作中，編寫文檔仍面臨挑戰。
圖片
圖片
文檔象限將其內容呈現方式劃定了明確的邊界，讓文檔看起來簡單明了，更適合對外輸出，幫助用戶快速上手。
結構化文檔之外似乎還存在另一種文檔組織方式：圖譜化，并且初具影響力。很多時候，為了保持文章的簡潔和內聚，我喜歡使用鏈接文字將一個相關概念指向別處。一旦順著鏈接深入幾層，就會發現文檔所承載的知識很快組成一張大網。知識圖譜一詞簡直恰如其分。自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://m.www897cc.com/showinfo-26-6163-0.html如何編寫技術文檔？
聲明：本網頁內容旨在傳播知識，若有侵權等問題請及時與本網聯系，我們將在第一時間刪除處理。郵件：2376512515@qq.com
下一篇： 基于靜態編譯構建微服務應用
Copyright ? 2016-2023 天津谷騏科技有限公司 版權所有 sitemap.xml
違法及侵權請聯系：2376512515@qq.com 津ICP備18001702號
津公網安備 12010102000574號