K60至尊版剛預熱 一加Ace2 Pro正面硬剛
Redmi這邊剛如火如荼的宣傳了K60 Ultra的各種技術和硬件配置，作為競品的一加也坐不住了。一加中國區總裁李杰發布了兩條微博，表示在自家的一加Ace2上早就已經采用了和PixelWo
為軟件系統編寫文檔在軟件開發中并不是什么新鮮事。幾乎每個人都明白這個原則:
你的軟件產品對用戶來說有多優秀并不是最重要的,因為如果你的文檔不夠好,用戶就不會使用它!即使在某些情況下用戶不得不使用你的產品,他們也需要好的文檔才能高效使用,否則可能會誤用你的產品。
不幸的是,幾乎沒有正確組織技術文檔的實踐和方法論。在團隊合作中,編寫文檔仍然面臨挑戰。
編寫技術文檔的任務似乎總是優先級很低:它需要大量時間,而且沒有立即的正面反饋!所以文檔編寫一再推遲,直到某個時候不得不完成,比如新團隊成員加入項目或我的開源產品即將發布時。只有到那時我才驚恐地意識到我沒有文檔。文檔最終被草草編寫,以至于完成后完全被忽視。隨著系統的發展,這些文檔逐漸脫節并變成謊言!這種說法乍一看似乎很荒謬,但在我周圍經常發生。
就像編寫代碼一樣,混亂的結構可能相當致命。我們可以使用類似 technical-writing-template 的東西來確保單篇文章的質量基于模板約定達到一定標準。然而,在復雜的軟件系統中,高質量的單篇文章是不夠的。許多優秀的軟件產品都有適當結構化的文檔,讓初學者和長期用戶都能輕松閱讀。我認為文檔無法擺脫混亂有幾個原因:
通過觀察優秀技術文檔的組織結構,如Unix手冊、Spring Boot或React,你會發現它們都是結構化的。主要用法是根據索引瀏覽感興趣的內容。
一般來說,編寫技術文檔基本上意味著編寫類似的結構化文檔。結構化文檔不僅是目前最主流的文檔組織方式,在可預見的未來也將如此。
保持清晰的結構絕非易事。作者很幸運地看到了一種確保正確生成結構化文檔的模式:文檔象限。
在坐標系中,將象限分為兩個軸描述文檔的屬性。橫軸描述文檔的使用場景是傾向于工作還是學習,縱軸描述是傾向于理論還是實踐。這四個象限分別是教程、操作指南、參考和解釋:
圖片
文檔象限為其內容的呈現定義了明確的界限,使文檔看起來簡單易懂,更適合對外輸出,并幫助用戶快速入門。
除了結構化文檔之外,似乎還有另一種組織文檔的方式:基于圖形,并且正在獲得影響力。通常,為了保持文章的簡潔性和連貫性,我喜歡使用鏈接文本指出其他地方的相關概念。一旦你深入幾層鏈接,你會發現文檔承載的知識很快形成一個大網絡。"知識圖譜"這個術語恰如其分。自2012年Google知識圖譜發布以來,知識圖譜的主要應用仍在搜索引擎和文獻檢索領域。像logseq這樣的產品采取了不同的方法,通過加強知識之間的聯系,以圖形化方式組織文檔。其主要用法涉及關鍵詞搜索結合跳轉到相關內容(鏈接引用)。
在使用 logseq 時,我發現這種方法更符合人類在大腦中構建知識模型的方式,有助于深入全面地理解問題。這與Luhmann的"Zettelkasten方法"產生共鳴。
我認為,基于圖形的文檔組織更適合作為團隊的知識庫,用于團隊內部的知識生產和管理。這與其主要操作模式有關。雖然我認為關鍵詞搜索是一種有效的方法,但它對新用戶的搜索能力提出了挑戰。
選擇參考
當你開始構建文檔時,即使沒有任何考慮,你也應該使用一些文檔工具或協作平臺來保存你編寫的文檔。我了解一些常用的文檔工具:
文檔生成工具:
文檔托管和協作:
圖形化文檔工具:
這些文檔構建方法和工具有什么用途?世界上可能沒有完美的軟件工具或系統能滿足所有個性化需求。當你選擇Google Docs進行協作編輯時,你將不得不處理大量樣式調整。當你使用Logseq作為團隊的內部知識庫時,其獨特的文檔標記格式使得遷移到其他工具變得困難。這令人沮喪!因此,構建文檔也需要類似的技術決策工作來確定適合的解決方案。這意味著在困難的權衡中做出選擇,選擇一個滿足要求的解決方案,其優點仍然鼓舞人心,而缺點是可以容忍的。
值得注意的是,具備編寫文檔的能力并不是唯一要求;在選擇解決方案時,我們似乎更重視功能之外的重要特性。是的,文檔構建也應該滿足可預見的非功能性需求:
令人興奮的文檔構建解決方案
使用Document Zenith組織內容,保存在Github等托管平臺上,并使用Sphinx生成電子書進行發布,或生成HTML進行私有部署。
優點:
缺點:
使用logseq作為知識庫,并將文檔保存在Github等托管平臺上。
優點:
缺點:
優點:
缺點:
本文鏈接：http://www.tebozhan.com/showinfo-26-112739-0.html我們一起聊聊如何編寫技術文檔
聲明：本網頁內容旨在傳播知識，若有侵權等問題請及時與本網聯系，我們將在第一時間刪除處理。郵件：2376512515@qq.com
上一篇： 這八 個常見的前端開源庫，你一定要知道！
下一篇： Python十大經典項目與實戰案例
Copyright ? 2016-2023 天津谷騏科技有限公司 版權所有 sitemap.xml
違法及侵權請聯系：2376512515@qq.com 津ICP備18001702號
津公網安備 12010102000574號