GaussDB(DWS)《構(gòu)建與崩塌之有效的指導(dǎo)文檔》

請寫一篇有效的指導(dǎo)文檔

為了讓大家盡快明白，我到底想表達什么。先提取兩個標(biāo)題中的關(guān)鍵詞，“有效”和“指導(dǎo)”。

有效

此處的有效，指通過閱讀和理解文檔中的方法和步驟，可以起碼依樣畫葫蘆的把文檔中的事情做起來，哪怕只是最基礎(chǔ)的程度。(文檔通過文字描述和圖片等等方式，傳遞完整的邏輯鏈給讀者)

指導(dǎo)

專門說明是指導(dǎo)類的文檔，是為了避免無效的討論。因為文檔的類型五花八門，有些文檔的目的，只是宏觀的討論如何去計劃或者一件事情，而不包含具體的執(zhí)行步驟，比如一些思路分享或者科普類的文檔。

有了上面兩點的認識基礎(chǔ)，我們再來討論，導(dǎo)致一篇指導(dǎo)文檔“無效”最常見的原因。

所以，對于操作中涉及的工具，即使不做對應(yīng)的講解，也提供個可以自行學(xué)習(xí)和下載的鏈接吧。我甚至遇到過，用到的工具有十幾個版本，文檔中既不提供工具，也不告訴你來源和版本的選擇。這種好像掌握了一條知識的邏輯鏈，但偏偏缺少幾個重要的環(huán)節(jié)，導(dǎo)致事情無法做下去的時候，真的是讓人有種“蜀道難，難于上青天”的感嘆！

其次，對于文檔中的一些專有名詞，尤其是英文字母縮寫的名詞，就算不做詳細的解釋，起碼給個英文全稱，讓人有處可查吧。

總結(jié)

能夠為了達成目標(biāo)，耐心去尋找和閱讀文檔的人，起碼都是有一定的求知欲和學(xué)習(xí)能力的人。不需要大家把飯喂到嘴邊，但起碼給條”求生之路“吧，至少要提供以下三點信息。

①關(guān)系到構(gòu)建完整認知邏輯的名詞，給出一定的解釋；

③完成目標(biāo)行為的完整步驟；

最后還是舉個例子，比如一篇從windows桌面提交代碼到代碼倉的操作指導(dǎo)文檔，至少包含以下信息。

①完整的步驟：

在代碼目錄下打開git bash->git add目標(biāo)文件->git commit提交請求->git push推送到個人分支->在個人分支中對比和主庫的差異，打開merge->通過各項流水線檢? ? ? 查后，發(fā)送鏈接給評審人員評審->符合合入條件后，找合并人合入merge

②相關(guān)工具獲取

git工具可以從華為工具云下載，無版本要求。直接默認步驟安裝后，參考xxxxxxx進行和代碼倉庫的鑒權(quán)配置。

③相關(guān)名詞解釋

git xxx為打開git bash后的具體操作指令，具體操作示例如下圖所示，xxxx

評審人員和合并人，會在打開的merge鏈接中顯示，如下圖所示,xxxx

當(dāng)然，上面的例子不一定完全準(zhǔn)確，比如一些名詞解釋，可能通過描述時的截圖就能說明了，不需要單獨去做說明。但是不管以什么形式呈現(xiàn)，這三點信息是一定要提供的。也就是說，指導(dǎo)文檔，要想達到目的：需要告訴讀者在理解某個邏輯后，使用什么工具，按照什么步驟來完成某件事情。一定不要讓關(guān)鍵細節(jié)的缺少，導(dǎo)致邏輯鏈斷掉！

EI企業(yè)智能 Gauss AP 數(shù)據(jù)倉庫服務(wù) GaussDB(DWS)

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。