Linux Foundation 專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

開放原始碼機構：
Linux 基金會
技術文件撰寫者：
jaskiratsingh2000
專案名稱：
CHAOSS：製作 CHAOSS 社群全體社群手冊
專案長度：
標準長度 (3 個月)

Project description

專案簡介：

目前，CHAOSS 社區的工作團隊已發展出自己的工作方式，並記錄各自不同的工作流程。工作團隊包括共同指標 WG、多元性與包容性 WG、進化、風險和價值等工作團隊，這些工作團隊已自行設立參與工作、工作方式，並採用不同的溝通與工作文化。這些以指標為依據的工作團隊，有不同的重點領域和背景，並引導各團隊在各自的工作團隊類別中進行各項研究與發展。此外，也知道引導新手和現有貢獻者完成各項研究與發展的正確途徑，但新手和現有貢獻者可能不知道如何參與或採取正確的行動。

因此，CHAOSS 社群中的內容並未標準化。因此，為瞭解整個社區工作文化的正確流程和基本原則，社群手冊的目標是整合關鍵資訊，並將整個 CHAOSS 專案中的部分資訊標準化。重要資訊和標準化部分主要著重在 CHAOSS 採用的流程，讓 CHAOSS 瞭解社群的完成方式、新加入者如何參與並遵循社群基礎知識，以及新手或現有成員必須遵循哪些程序和途徑，才能成為 CHAOSS 社群中的領導能力。

本手冊是 CHAOSS 專案中的作業手冊，方便現有社群成員及新成員完成工作。這項專案包含了收集及管理手冊內容的廣告素材元件，同時也是定義手冊呈現方式的技術元件。

使用須知

《社群手冊》是一份文件，載明社群的重要政策與程序，當中概述社群的使命、價值觀和工作。

本手冊針對新加入的社群成員提供清楚的說明以及各方面的協助。 目前 GitHub 存放區提供 CHAOSS 社群手冊，需要為新手及現有社群使用者提供更多詳細資訊並進行重構。因此，這篇 CHAOSS 社群討論手冊可為新手和現有社群成員透過下列方式提供協助：

  • CHAOSS 社群制定政策並加以整理，將所有政策集中在同一處
  • 與社群中的介紹、使命、願景和領導能力溝通
  • 瞭解 CHAOSS 社群實務規範
  • 貢獻指南
  • 定義專案工作流程
  • 描繪 CHAOSS 社群文化
  • 一般常見問題
  • 輔導服務

專案說明：

社群手冊分為多個「版面」，其中包含特定主題的適當詳細資訊。分類夾可透過下列方式劃分：

  • 簡介
  • CHAOSS 社群的拍攝方式
  • 主管階層路徑
  • 術語
  • 貢獻指南
    • 開發人員
    • 設計人員
    • 寫入者
    • 行銷人
  • 指標
  • CHAOSScon
  • CHAOSScast
  • 會議影片
  • 一般常見問題
  • 指導
    • Google 夏季程式碼
    • 外聯
    • Google 系列文件

詳細專案可淘汰項目

1.) 簡介：

本節將做為 CHAOSS 社群手冊的第一頁，涵蓋本手冊的詳細資料、總覽和使用方式。請留意下列事項：

A.) 當中會顯示歡迎訊息，並附上 CHAOSS 社群的簡短說明，有助於說服讀者閱讀手冊。我也要附上從這裡 https://chaoss.community/chaoss-photo-Album/ 拍攝的圖片美術拼貼，以便凸顯社群內各種流動人物。 B.) 網頁上也會列出所有章節的詳細資訊，並以單行說明解釋每個章節和適當的連結。 C.) 手冊使用情況：這裡已經存在( shorturl.at/cqQU6 )，但我將改良並重構現有的手冊使用情形，並以更明確的標示方式重構，其中包括手冊流程(內容包括有人想新增、移除或討論與手冊相關的事情。且追蹤處理任何與手冊相關問題的通訊流程)。手冊指南(包括在社群和範圍內的使用)、對手冊的貢獻 ( 包括應如何使用存放區來進行變更、製作 PR、遵循手冊和樣式指南變更的範本)，以及分享有關手冊的意見回饋。在「分享意見回饋」中，我會加入範本和各種追蹤方式，讓使用者瞭解提供或使用 GitLab 問題的方式。

2.) CHAOSS 社群的拍攝方式：

CHAOSS 社群的合作方式是讓人們瞭解社群實踐與規範的關鍵。Workflows 可以用更強調的方式，以最佳方式概述社群做法。這個部分包含以下內容：

A.) 一般價值：簡要說明 CHAOSS 社群如何處理永續發展、開放性和資訊公開。我會說明這些價值觀，讓新使用者或現有使用者在與社群互動時，應該如何解讀及考量這些價值。 B.) 社群規範：包括實際加入 CHAOSS 社群的方式，並遵循基本條款。這也說明社區內追蹤的工作文化。(建議做法)。課程會包含核心貢獻者/維護者檢查清單，協助他們瞭解自己與維護人員合作的方式和檢查清單。 C.) 工作群組：此頁面( https://chaoss.community/participate/ ) 包含工作小組的相關資訊，例如 WG、存放區連結和會議資訊，但在手冊中，我將說明參與不同工作團隊和評估指標的過程、瞭解個別 WG 的工作文化，以及如何成為不同工作團隊的核心貢獻者。

3.) 主管階層路徑：

但在開放原始碼專案取得領導地位，對社群在商業世界中邁向成功至關重要。因此，我必須考量下列事項：

A.) 技術領導團隊：這包括存放區維護人員、文件寫入者和網站維護人員 B. 的程序和責任。)管理主管：包含董事會成員和決策者 C.)營運領導團隊：包含社群管理員課程

4.) 術語：

術語有助於描述 CHAOSS 社群中常用的字詞與各自物品。此外，我也會附上術語使用指南，例如大寫、縮寫和應避免的字詞。 受影響的條款包括 CHAOSS 專案、開放原始碼社群健康、程式碼審查、工作團隊、開放原始碼軟體指標、共同指標、多樣性和包容指標、演變工作團隊、風險工作小組、價值工作團隊、指標發布、重點領域。

5.) 貢獻指南：

大部分的開放原始碼社群都是以這些來源貢獻內容，因為大部分的開放原始碼社群都仰賴貢獻或志工服務，因此能協助加入社群的新手/使用者瞭解必須遵循的基本要求和規範。因此會包含下列詳細資料：

A.) 瞭解社群發展藍圖：本主題將概略介紹 CHAOSS 社群的發展藍圖，協助使用者瞭解遵循 CHAOSS 專案中各種工作的方式或流程。B.) 說明進行任何貢獻 (例如開發、說明文件、設計、測試等) 時所需的必要資訊)。概略介紹 GitLab 工作 D.)審查人員/維護人員指南

這個部分也會包含各「貢獻」類別的「角色和責任」，如下所示：

a.) 設計：本子章節包含「CHAOSS 設計工作流程」和《設計指南》，其中包括設計原則、程序和使用工具，讓協作者在對設計欄位貢獻心力時必須遵循這些原則。 b.)開發：這包含程式碼集貢獻指南。其中包含技術相關規定、專案結構、專案設定(Augur、Cregit、GremoireLab) c.)說明文件：包括說明文件資源，包括工具和樣式指南。 d.)參與者：這包括貢獻者如何協助 CHAOSS 社群推動外聯成長，例如撰寫網誌、使用社會帳號代碼、規劃聚會和活動

6.) 指標

目前 CHAOSS 社群網站提供 Metric Releases( https://chaoss.community/metrics/ ) 的資訊，因此對使用者而言更需要瞭解如何按照程序，在該網站提供指標網站。因此，本節介紹的資訊可協助使用者瞭解相關程序及如何釋出指標。

7.) CHAOSScon：

GitHub( https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md ) 和網站( https://chaoss.community/CHAOSScon-2020-NA/ ) 上已有 CHAOSScon 的相關資訊，但更明智地在 CHAOSScon 管理 CHAOSScon 的詳盡程序及管理方法。手冊中將包含以下資訊：

A.) 委員會相關詳細資料：其中會說明加入 CHAOSScon B 的組織委員會的程序)。提案流程的呼叫管理：這包括管理作者登記、提交提案與文件、審核與核准程序。 C.) CHAOSScon 計畫的管理及發布作業 D.)如何管理廣告和行銷內容 E.)如何處理包版提案和 (包含套裝方案) 資金

8.) CHAOSScast：

如需 CHAOSScast 資訊，請參閱 https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md。《手冊》中也會收錄 CHAOSScast 資訊，並附上參與、組織委員會、廣告與行銷材料等額外詳細資料。

9.) 會議影片：

這些資料將涵蓋過去所有會議影片，以及過去在 YouTube 上提供觀看的說明影片，例如參與者和議程。

10.) 一般常見問題：

其中包含社群中常見的常見問題，將有助於新手和現有社群成員解答部分問題。

11.) Google Summer of Code：

本節將說明 Google Summer of Code、資格條件，以及「Google Summer of Code」中 CHAOSS 社群的參與方式。這個部分也包含「提案範本」，可供人員用來草擬提案、角色和職責。 此外，您也能在課程中取得相關資訊，協助現有社群成員瞭解成為機構組織管理員與導師的過程。

  1. 外聯：

本節將說明「外聯」、「資格條件」標準，以及員工在 Outreachy 的 CHAOSS 社群參與方式的相關資訊，以及角色和職責，包括成為機構管理員和導師的過程。

  1. Google 系列文件：

本節將介紹 GSoD、資格條件標準，以及人們在 GSoD 中參與 CHAOSS 社群的方式相關資訊。課程中會說明角色和職責，包括成為機構管理員和導師的過程。

預期專案成果：

手冊在任何社群中都扮演著重要的角色。同樣地，這份全套 CHAOSS 社群手冊為 CHAOSS 社群提供條理分明且詳盡的說明文件。無論是剛加入社群的新手，還是社群中的現有成員，都可以輕鬆瞭解 CHAOSS 社群的基礎和運作原理。 此外，這份手冊將為 CHAOSS 社群中的不同工作文化建立各種流程和路徑。

技術詳細資料：

我建議使用 Gitbook 平台維護手冊，因為這個平台容易使用且容易協作，可讓團隊更有效率地工作。GitBook 平台的部分功能：

  • WYSIWYG：功能強大卻精美的文字編輯器
  • Markdown：和 Markdowns 捷徑的強大和高效支援
  • 互動式多媒體：嵌入外部網頁內容，例如影片、程式碼片段、文章、音樂等等
  • 撰寫者專用的資訊主頁：有了專為寫作家打造的智慧資訊主頁，支援視覺編輯功能
  • 草稿：草擬新變更並非同步協作
  • 支援註解：討論及檢閱草稿變更
  • 追蹤書寫記錄：追蹤所有內容。查看及還原變更
  • 深入分析：同時提供洞察資料，追蹤流量、評分和內容品質
  • GitHub 同步處理：保留工作流程並繼續將文件與 GitHub 保持同步
  • 自訂品牌宣傳：自訂網域、自訂標誌、字型、顏色、主題、標頭等

以下列舉幾張圖片能讓你快速瞭解這個平台

  • shorturl.at/GNQR4
  • shorturl.at/gATZ8
  • shorturl.at/qrE57
  • shorturl.at/rFRX6
  • shorturl.at/eyLW1
  • shorturl.at/rwHS8

-- 手冊收錄在哪裡？

手冊將託管於 GitBook 本身，GitHub 為自訂網域、一般錯誤及搜尋引擎最佳化 (SEO) 提供適當機制。

自訂網域： 如果 CHAOSS 社群想將網域託管於自訂網域，請用 docs.chaoss.community 的形式顯示，而且只需建立任何想擁有的子網域即可。如要設定機構網域，請前往 Gitbook 平台中的機構設定。圖片範例：shorturl.at/GNQR4

GitBook 空間會透過我們的 CDN 提供，而且預設啟用 HTTPS。憑證是由 LetsEncrypt 核發

支援的網域：

  • 子網域：www.example.com
  • 自訂網域：docs.example.com

-- 如何同步處理 Gitbook 與 GitHub，以便可在兩個平台有效編輯？

與 GitHub 整合相當容易：只要有人變更 GitBook 上的部分內容，他們的編輯內容就會推送至 GitHub 存放區。反之，推送至 GitHub 存放區的修訂版本會匯入 GitBook。

設定 GitHub 整合：

  • 在 GitBook 平台中的空間中，依序點選「Integration」分頁標籤 > GitHub
  • 授權 GitBook 存取與貴機構連結的 GitHub 帳戶
  • 前往您的機構 GitHub 並建立「HandBook」的存放區，例如 chaoss-handbook
  • 現在選取您要在 GitBook 平台的授權選項中連線的存放區，並命名為 chaoss-handbook。

完成上述步驟後，GitBook 會將 Webhook 新增至 Chaoss-handbook 存放區，以便在每次存放區發生任何變更時都能擷取內容。變更 GitBook 時，系統會推送新的註解。

這樣就大功告成了！任何人都可以繼續透過 GitBook 或 GitHub 存放區編輯。

-- 如何在 GitBook 平台上編輯頁面？

凡是要在 GitBook 平台中編輯任何內容的使用者，都必須透過邀請或加入連結加入 GitBook 平台。GitBook 支援視覺化編輯功能，可讓使用者直接在頁面中編寫內容。

草稿是一種可編輯的使用者內容，只有撰寫者才能存取，而且系統會在你開始撰寫內容後自動建立草稿 (編輯時首次寫信、建立新頁面、上傳圖片等)。

修改草稿內容具有適當效果，讓您可以與其他成員同時在同一份文件上協作，而不會造成任何衝突！這就是所謂的非同步編輯和衝突解決方案。

草稿的第一個版本不一定能立即發布，如果您想稍後再繼續作業，或者內容尚未準備好要「合併」時，請使用「儲存」。

編輯完成後，您可以「合併」草稿。完成後，您的團隊成員及/或公開您撰寫的內容或所做的變更。

圖片範例：shorturl.at/gATZ8 和 shorturl.at/qrE57

-- 內容結構：

目錄：每個空間可包含您需要撰寫文件所需的頁面數量。在我們所謂的「目錄」中，您可以在畫面左側看到這些網頁。您可以透過「目錄」管理網頁：建立新頁面、一組頁面、新增外部連結、新增外部連結、匯入外部文件，例如 Markdown (.md 或 .markdown)、HTML (.html)、Microsoft Word (.docx)。

初始頁面： 初始頁面是指說明文件的首頁或根層級，基本上可做為說明文件所有頁面的主頁。因為這是文件和空間的主要入口，因此無法移動、刪除、擁有兒童或屬於群組。

頁面：在編輯器頂端含有標題和選填說明。接著，您可以撰寫及新增任何類型的內容。您可以將頁面拖曳到另一個頁面下方，藉此建立巢狀結構頁面。網頁的子項會隱藏，但可收合。

外部連結：這些項目屬於外部連結，編輯器中不含任何內容。主要功能是連結至外部網站。

變化版本：您可以建立變化版本，為說明文件建立替代內容。方便您記錄多個 API 版本、程式庫或翻譯。

圖片範例：shorturl.at/eyLW1 和 shorturl.at/rFRX6

-- 手冊如何顯示在用戶端上？

Chaoss 社群手冊可透過 https://docs.chaoss.community 存取 存取，使用者端會呈現以下幾種方式：

  • Mattermost 手冊 - https://handbook.mattermost.com/
  • Linux 基礎社群橋接文件 - https://docs.linuxfoundation.org/docs/ 還有更多

專案時程：

1.) 社群凝聚階段 (8 月 17 日至 9 月 13 日)

A.) 第 1 週 - 4 週：

  • 與導師討論專案
  • 研究並收集專案中各部分所需的資訊，向社群成員釐清問題
  • 與社群說明該使用哪個平台製作手冊 (我建議使用 GitBook)，並進行相關設定
  • 協助解決文件問題

2.) 文件開發階段 (9 月 14 日至 11 月 30 日)

A.) 第 5 週 (9 月 14 日至 9 月 20 日)

  • 草稿」簡介部分

B.) 第 6 週 (9 月 21 日至 9 月 27 日)

  • 草擬「CHAOSS Community Way」區段

C.) 第 7 週 (9 月 28 日至 10 月 4 日)

  • 草擬「領導階層路徑」部分
  • 草擬「術語」部分

D.) 第 8 週 (10 月 5 日至 10 月 11 日)

  • 草擬社群發展藍圖
  • 草擬設計提供指南

E.) 第 9 週 (10 月 12 日至 10 月 18 日)

  • 草稿開發專區

F.) 第 10 週 (10 月 19 日至 10 月 25 日)

  • 撰寫與推廣部分指南

G.) 第 11 週 (10 月 26 日 - 11 月 1 日)

  • 「草稿指標」區段
  • 「CHAOSScon 草稿」區段

H.) 第 12 週 (11 月 2 日至 11 月 8 日)

  • 設計會議專區

  • 社群一般常見問題草稿

    I.) 第 13 週 (11 月 9 日至 11 月 15 日)

  • GSoC 指南草案

J.) 第 14 週 (11 月 16 日 - 11 月 22 日)

  • 推廣指南草稿

K.) 第 15 週 (11 月 23 日至 11 月 29 日)

  • 緩衝時間；修飾與改善整份文件

3.) 評估階段 (11 月 30 日至 12 月 5 日)

A.) 第 16 週：

  • 擬定專案報告
  • 填寫專案的評估作業

社群互動

1.) 與社群參與及討論。

我從 2020 年 4 月開始到 CHAOSS 社群，持續與社群成員進行各種討論，並與我的專案導師( Georg Link 和 Armstrong Foundjem) 互動。其中一個廣受社群成員關注的討論是「提議將 Gitbook 做為代管社群手冊的平台」，在 CHAOSS 封存郵寄清單會話串中找到，名稱為「Proposing Gitbook」做為代管社群手冊的平台。我也一直參與社群每週通話，幫助我為社群提供最新資訊。

2.) 您要如何收集本專案所需的資訊？

由於這項專案需要設定全社群手冊，因此系統會向社群成員收集需要存取的資訊，並與社群成員討論。如同我先前建議我的時間表，我將根據這些建議，在社群凝聚期間討論及收集所需資訊。

我將根據 CHAOSS 研究各個章節，並持續透過郵寄清單掌握討論串。我會依照要求，向導師和社群成員釐清問題。

為了方便討論，我也將每週通話一次。

3.) 您會如何提議，幫助社群掌握您的進度，以及您在專案過程中可能遇到的任何問題？

為求彈性與資訊公開，我會試著透過郵寄清單討論，解答任何疑惑。

我將透過網誌文章分享每週進度，並在社群郵寄清單中分享 Scrum 文件和麵臨的挑戰，以便觸及更多開放原始碼組織內的目標對象。

我也將參加每週的社群通話，以便針對主要問題提供適當的建議和討論。

我同時打算製作 Trello 白板，介紹每週可用的任務。導師之後就可以使用這個白板，簡明扼要地瞭解目前的問題和功能。

4.) 如果專案受阻，而導師不在身邊，你會怎麼做？

我認為這位導師的角色是引導學生採取適當方向，而不是分別解釋學生的每個迴圈。研究和實作專案是學生的唯一責任。請注意，我只有在不得已時才嘗試向導師尋求協助。

不過，如果導師不是在我需要協助的地方，我就會繼續在 CHAOSS 社群中分享我遇到的問題。我相信一定有人能幫我解決任何我出現的挑戰。我也會在 dev.to 等線上論壇/開發人員社群中分享這個問題

此外，我會嘗試每週前往 CHAOSS 社群尋求幫助，自行發問。