蜜桃av色欲a片精品一区,麻豆aⅴ精品无码一区二区,亚洲人成网站在线播放影院在线,亚洲 素人 字幕 在线 最新

  文檔并不是開源項目開發(fā)的附屬品

發(fā)布日期：2022/5/6 11:24:57      瀏覽量：

有些項目長期保持活躍，有些項目卻過早消亡 —— 這兩者的區(qū)別往往在于它們的文檔。嚴(yán)謹(jǐn)、聰明的文檔可以給你的項目帶來它所需要的動力。你應(yīng)該把文檔工作視為一項主要工作，把它與開發(fā)相提并論，下面我將說明這么做的理由和正確的做法。

經(jīng)常會有開發(fā)者簡單地認(rèn)為他們的代碼的“自我描述self-documented”已經(jīng)足夠了，繼而認(rèn)為額外的文檔是沒有必要的。這種過度的自信會讓項目付出很大的代價。匱乏或差勁的文檔會扼殺你的項目。沒有適當(dāng)?shù)奈臋n，用戶將無法理解項目的目標(biāo)以及正確的工作流程。這可能會導(dǎo)致人們對采用你的開源產(chǎn)品產(chǎn)生一些疑慮。
撰寫文檔，從項目第一天就開始
文檔不應(yīng)該是次要的工作，它應(yīng)該是與代碼開發(fā)和管理同等的主要任務(wù)。隨著內(nèi)容以 Community Threads、Stack Overflow 和 Quora 問答等形式的廣泛傳播，文檔承擔(dān)了“信息源source of truth”的角色。它應(yīng)該滿足那些想?yún)⒖家皇仲Y料的貢獻(xiàn)者的需要，并給工程師提供必要的參考支持。它還應(yīng)該與利益相關(guān)者溝通基本計劃。一個好的文檔可以確保產(chǎn)品的持續(xù)改進和發(fā)展。
當(dāng)發(fā)布一個軟件產(chǎn)品時，我們不僅要發(fā)布代碼，還要發(fā)布好的文檔。這給我們帶來了一個最重要的概念，大多數(shù)良好維護了文檔的開源項目都遵循這個概念 —— “文檔即代碼Documentation as code”。
文檔及代碼
今天，文檔不再被存儲為微軟 Word 或 PDF 文件。新的需求是版本控制文檔，其中所有的文檔都是通過版本控制系統(tǒng)添加的，并持續(xù)發(fā)布。這個概念因 Read the Docs（LCTT 譯注：一個文檔創(chuàng)建、托管和瀏覽的平臺）而流行，現(xiàn)在已經(jīng)成為大多數(shù)文檔團隊的內(nèi)容策略的重要組成部分。
像 Bugzilla 和 GitHub 議題Issue這樣的工具可以用來跟蹤待處理的文檔工作，并從維護者和用戶那里獲得反饋以驗證文檔的發(fā)布。外部審查可以用來驗證文檔作品，并持續(xù)發(fā)布文檔。這就保證了除代碼外，文檔也能不斷改進并快速發(fā)布。
請記住，如果不遵循規(guī)范化的實踐，每個文檔都會不同。這可能會導(dǎo)致一些混亂，使人們難以獲取正確的信息。
哪些東西會被歸類為混亂呢？當(dāng)大多數(shù)文件都不遵循規(guī)范實踐時，不一致就會產(chǎn)生，從而導(dǎo)致更大的混亂！那么，如何整理混亂的開源文檔呢？
整理混亂的開源文檔
遵循一個“文檔風(fēng)格指南”是很重要的。風(fēng)格指南是創(chuàng)建和展示內(nèi)容的指導(dǎo)方針的集合。無論你是一個獨立的作家還是一個大型文檔團隊的成員，它都有助于在你的文檔中保持一致的風(fēng)格、口音和語氣。
有幾個流行的風(fēng)格指南，如《紅帽風(fēng)格指南》、《谷歌文檔風(fēng)格指南》和《蘋果風(fēng)格指南》。如何選用？首先要從定義你的需求開始。如果你的要求與其他開源項目沒有太大區(qū)別，你可以遵循一個現(xiàn)成的風(fēng)格指南，或者你也可以先選一個，然后在它的基礎(chǔ)上根據(jù)自身需要做一些修改。大多數(shù)與語法有關(guān)的準(zhǔn)則和內(nèi)容規(guī)則可能是通用的，但整體術(shù)語可能會有所不同。
你還需要在你的項目中自動采用這些風(fēng)格指南。為此，你可以使用 Vale，它集成了本地的持續(xù)集成（CI）服務(wù)，該服務(wù)能幫助你確保文檔嚴(yán)格遵循風(fēng)格指南。
文檔類型 自述文件：包含基本的安裝和使用說明，這也是任何開源文檔中最重要的部分之一。它是潛在的用戶/開發(fā)者與項目之間的第一個連接點。 參考指南：可能包括一些基本的參考資料，以便幫助你快速上手，或者是與項目貢獻(xiàn)相關(guān)的文檔。 用戶文檔：是最基本的文檔，它描述了項目的使用方式。如果沒有用戶文檔，大多數(shù)人就會對如何使用該項目感到迷茫。 開發(fā)文檔：旨在支持開發(fā)團隊在項目中不斷取得新的進展。它還應(yīng)該為內(nèi)部開發(fā)工作提供一個良好的途徑，并確保功能被很好地傳達(dá)給股東。 社區(qū)內(nèi)容：包括基本的博客、視頻和外部內(nèi)容，旨在為那些想進一步了解項目的社區(qū)成員提供支持。
通過使用風(fēng)格指南，文件的整體前提將以統(tǒng)一的語言風(fēng)格傳達(dá)給用戶。但是，這些文件畢竟是由一個技術(shù)作家團隊準(zhǔn)備的，它們的寫作風(fēng)格可能會沖突，因為寫作風(fēng)格是因人而異的。那么，如何才能使文檔規(guī)范化呢？
規(guī)范化文檔
當(dāng)涉及到規(guī)范化文檔時，有許多方法可以采取。第一個方法顯然是創(chuàng)建適用于各種角色的預(yù)定義模板。這些模板可以用來記錄新的功能、識別錯誤和問題，以及更新變更日志以適應(yīng)正在增加的新內(nèi)容。
如果你采用的是基于 Git 的工作流，試著開發(fā)一個規(guī)范的工作流程來發(fā)布你的文檔。最規(guī)范的工作流是：復(fù)刻fork 發(fā)布文檔的倉庫，在本地分支上添加你的修改，推送這些修改，提出請求并要求對其進行審查。規(guī)范化文檔的一個好處就是帶來更好的反饋和審查過程。
反饋和自動審查
規(guī)范化使得你能夠得到用戶的反饋并生成自動的審查，可以參考這些反饋來改進項目和文檔。通過這些反饋，你也可以評估所分享的信息對用戶是否有意義。像 GitBook 這樣的文檔平臺會提供合適的反饋服務(wù)，這有助于驗證文檔是否有用。
始終尋求主題專家subject matter expert（SME）對文檔的反饋，他們可以是利益相關(guān)者、開發(fā)者、工程師，甚至是外部貢獻(xiàn)者。你也可以使用自動測試和 CI 來驗證你的文檔是否遵循風(fēng)格指南。
文檔眾包
如果你想開源你的文檔，最好的方法也許是提供一個快速入門指南。它可以像 CONTRIBUTING.md那樣簡單，基本上只要說明該如何設(shè)置項目并為其作出貢獻(xiàn)/單純使用它即可。
始終開發(fā)以用戶為中心的文檔，標(biāo)明每個項目的目的。同時，打造學(xué)習(xí)課程來幫助新的貢獻(xiàn)者。
帶著目的編寫文檔 始終帶著目的編寫文檔。它是最基本的寫作策略之一，它定義了你編寫某個特定文檔的理由，而非方式。首先回答以下問題： 這個文檔的目標(biāo)是什么？ 需要傳遞的信息是什么？ 你希望用戶在這之后采取什么行動？ 我與讀者分享的價值觀是什么？ 我的文檔風(fēng)格是否簡潔、一致？

定義一致的內(nèi)容策略
一致的內(nèi)容策略有助于確保文檔工作和項目基礎(chǔ)設(shè)施的長期愿景。它可以圍繞以下兩個主要方面：
1. 資源：包括項目文檔、案例研究和白皮書、項目架構(gòu)等
2. 品牌內(nèi)容：博客和特邀帖子、新聞和社區(qū)故事、學(xué)習(xí)課程等
每個開源項目都應(yīng)該有適當(dāng)?shù)奈臋n，以說明它能為用戶提供的功能，這樣用戶就可以選擇最合適的解決方案。適當(dāng)?shù)奈臋n可以傳達(dá)正確的信息，也可以讓其他開發(fā)者貢獻(xiàn)力量來進一步加強和改進項目。雖然聽起來很簡單，但只有做對了，文檔才能成功。而你的項目，反過來，只有在你的文檔正確的情況下才能成功，所以永遠(yuǎn)不要低估它的目標(biāo)或過程！
策劃：Laveesh Kocher
via: https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/
作者：Harsh Bardhan Mishra選題：lkxed譯者：lkxed校對：wxy
本文由 LCTT原創(chuàng)編譯，Linux中國榮譽推出