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