Linux Foundation 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
Linux 基礎
技術文件撰稿者：
jaskiratsingh2000
專案名稱：
CHAOSS：建立 CHAOSS 社群全體手冊
專案長度：
標準長度 (3 個月)

Project description

專案摘要：

目前，CHAOSS 社群的工作小組已自行開發工作方式，並記錄不同程度的不同程序。工作小組包括通用指標 WG、多元與包容 WG、進化、風險和價值工作小組，這些小組已設定參與和工作方式，並採用不同的溝通方式和工作文化。這些工作小組根據指標，有不同的重點領域和背景，可針對適當的指標，領導各個工作小組類別下的各種研究和開發工作，並瞭解如何在各個類別下，以正確的方式領導各種研究和開發工作，但新手和現有貢獻者可能不瞭解如何參與或採用正確的做法，以便進行各項工作。

因此，CHAOSS 社群中的事物並未標準化。因此，為了瞭解社群中工作文化的正確程序和基本原則，社群手冊的目標是將重要資訊集中管理，並在 CHAOSS 專案中將部分資訊標準化。重要資訊和標準化部分主要聚焦於 CHAOSS 使用的流程，讓 CHAOSS 達成社群成就的運作方式、新玩家可以參與並遵循社群的基礎概念，以及新手或現有成員須依循哪些流程和途徑與 CHAOSS 社區中的領導人操作。

對現有社群和新社群成員來說，這份手冊應說明如何完成 CHAOSS 專案工作。這個專案包含創意元素，負責收集和整理手冊內容，以及技術元素，負責定義如何呈現手冊。

客戶需求

《社群手冊》一份文件，詳細定義了社群的主要政策和程序，並說明社群的使命、價值觀和工作成果。

本手冊為新加入社群的成員提供清楚的介紹和操作說明。目前，CHAOSS 社群手冊已在 GitHub 存放區上架，但需要重新設計和重構，以便為新手和現有社群使用者提供更多資訊。因此，這本 CHAOSS 社群手冊將以以下方式協助新手和現有社群成員：

  • 正式制定並整理 CHAOSS 社群的政策，將所有政策集中於一處
  • 說明社群的簡介、使命、願景和領導團隊
  • 瞭解 CHAOSS 社群的做法
  • 參與規範
  • 定義專案工作流程
  • 概述 CHAOSS 社群文化
  • 一般常見問題
  • 輔導服務

專案說明：

社群手冊分為多個「單元」，其中包含特定主題的適用資訊。並透過下列方式區分這些專區：

  • 簡介
  • CHAOSS 社群
  • 領導之路
  • 術語
  • 參與規定
    • 開發人員
    • 設計人員
    • 寫入者
    • 行銷人員
  • 指標
  • CHAOSScon
  • CHAOSScast
  • 會議影片
  • 一般常見問題
  • 指導計畫
    • Google Summer of Code
    • 外聯
    • Google 的「Documentary Season」

詳細的專案可交付成果

1.) 簡介：

本節將做為 CHAOSS 社群手冊的第一頁，並說明手冊的詳細資訊、總覽和用法。包括：

A.) 這封電子郵件會包含歡迎訊息，簡要說明 CHAOSS 社群，讓讀者有動力閱讀手冊。我也會加入從以下網址擷取的圖片拼貼畫面：https://chaoss.community/chaoss-photo-album/，以便凸顯社群中的各種動作。B.) 這個頁面也會包含所有部分的詳細資料，並以一行說明解釋每個部分和適當的連結。C.) 手冊用法：手冊用法已存在於此( shorturl.at/cqQU6)，但我會使用更優異的 Markdown 重新設計及重構現有的手冊用法，其中會納入手冊的流程(我會說明使用者想要新增、移除或討論與手冊相關的內容時，會發生什麼事)。如有任何手冊相關問題，可能會透過這項程序進行後續追蹤。手冊指南(包括在社群和範圍內使用)、對手冊的貢獻 ( 包括說明應如何使用存放區進行變更)、建立 PR、遵循教戰手冊和樣式指南變更的範本)，以及分享有關手冊的意見。在「分享意見」中，我會提供範本和各種方式，讓使用者可以追蹤並提供意見，或使用 GitLab 問題來接收意見。

2.) CHAOSS 社群的做法：

為了讓使用者瞭解社群慣例和規範，CHAOSS 社群會提供相關資訊。工作流程可讓您更有效率地強調並概述社群做法。本節包含以下內容：

A.) 一般價值：概述 CHAOSS 社群對於永續發展、開放性和透明度的處理方式。我將說明這些值，讓新使用者或現有使用者瞭解這些值，並在與社群合作時加以考量。B.) 《社群規範》：說明使用者如何參與 CHAOSS 社群，以及遵守基本條款。也會說明社區成員採取的工作文化。(注意事項)。其中包含核心貢獻者/維護者的檢查清單，並讓他們知道如何與維護者合作，以及檢查清單內容。C.) 工作團隊：這個頁面( https://chaoss.community/participate/ ) 包含工作團隊的相關資訊，例如工作團隊說明、存放區連結和會議資訊，但在手冊中，我會說明如何參與不同工作團隊，以及如何評估指標、瞭解各個工作團隊的工作文化，以及如何成為不同工作團隊的核心貢獻者。

3.) 領導之路：

雖然在開放原始碼專案中取得領導地位，對於社群在商業領域的成功至關重要，因此，考量到這點，我會納入以下內容：

A.) 技術主管：這項工作包括設定存放區維護者、文件編寫者和網站維護者的程序和職責 B.) 治理領導：這會包括董事會成員和決策者的途徑 C.) 營運主管：這會包含社群管理員的路徑

4.) 術語：

術語可協助說明 CHAOSS 社群中經常使用的詞彙和相關內容。此外，我也會提供相關的使用規範，例如大寫字母、縮寫和應避免使用的字詞，並說明原因。這些條款包括：CHAOSS 專案、開放原始碼社群健康、程式碼審查、工作小組、開放原始碼軟體指標、通用指標、多元與包容指標、演進工作小組、風險工作小組、價值工作小組、指標發布、重點領域。

5.) 參與規定：

這是任何開放原始碼社群的主要背景，因為大多數開放原始碼社群都仰賴貢獻或志願工作，因此這有助於任何加入社群的新手/使用者瞭解必須遵循的基本必要條件和規範。因此，其中包含下列詳細資料：

A.) 瞭解社群藍圖：本主題將概略說明 CHAOSS 社群的藍圖，協助使用者瞭解如何在 CHAOSS 專案中，為各種工作指定優先順序。B.) 說明任何實作貢獻 (例如開發、文件、設計、測試等) 所需的必要事項 C.) 簡要介紹 GitLab 的運作方式 D.) 審查人員/維護者指南

本節也會說明各貢獻類別的「角色和責任」，如下圖所示：

a.) 設計：這個子區段將包含「CHAOSS 設計工作流程」和設計指南，其中包含設計原則、程序和工具，貢獻者在設計領域提供貢獻時必須遵循。 b.) DEVELOPMENT：這包含對程式碼集的貢獻指南。其中包含技術需求、專案結構、專案設定(Augur、Cregit、GremoireLab) c.) 說明文件：這裡應包含說明文件的資源，包括工具和樣式指南。 d.) 宣傳：這項內容將說明貢獻者如何協助 CHAOSS 社群擴大宣傳範圍，包括撰寫部落格、使用社群帳號、舉辦聚會和活動

6.) 指標

目前，CHAOSS 社群網站提供了 Metric Releases( https://chaoss.community/metrics/ ) 的資訊，因此使用者必須瞭解如何遵循相關程序，才能在該網站提供指標網站。因此，本節將提供資訊，協助使用者瞭解相關程序和工作，以便發布自己的指標。

7.) CHAOSScon：

CHAOSScon 的相關資訊已在 GitHub( https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md) 和網站( https://chaoss.community/CHAOSScon-2020-NA/ ) 上提供，但在手冊中加入說明 CHAOSScon 程序和管理方式的詳細資訊和資訊會更合理。手冊中會包含以下資訊：

A.) 關於組織委員會的詳細資訊：將說明參與 CHAOSSconB 的組織委員會的過程。)提案呼叫管理：包括管理作者報名資料、提交提案和文件、審查及核准程序。 C.) 管理及發布 CHAOSScon 計畫 D.) 如何管理廣告與行銷相關內容 E.) 如何處理贊助提案和資金 (包括套裝方案)

8.) CHAOSScast：

CHAOSScast 資訊位於以下網址：https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md，並會納入手冊，提供參與、籌備委員會、廣告和行銷素材等其他詳細資訊。

9.) 會議影片：

這份清單會列出所有會議影片，以及與會者、議程等說明，這些資訊會在 YouTube 上提供。

10)一般常見問題：

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

11.) Google Summer of Code：

本節將說明 Google 程式設計夏令營、資格條件，以及使用者如何透過 CHAOSS 社群參與 Google 程式設計夏令營。這個部分也會提供「提案範本」，供使用者擬定提案、角色和職責。 此外，這份文件也會提供資訊，協助現有社群成員瞭解如何成為機構管理員和導師。

  1. Outreachy：

本節將說明 Outreachy、資格條件，以及參與 Outreachy 的 CHAOSS 社群的相關資訊。這裡會說明角色和責任，包括成為機構管理員和導師的程序。

  1. Google 文件季節：

本節將說明 GSoD、資格條件，以及參與 CHAOSS 社群的 GSoD 相關資訊。這份文件會說明各項角色和責任，包括成為機構管理員和導師的程序。

專案預期成果：

手冊在任何社群中都扮演著重要的角色。同樣地，這本 CHAOSS 社群手冊將為 CHAOSS 社群提供更有條理且詳細的文件。這樣一來，不論是加入社群的新成員，還是社群內的現有成員，都能輕鬆瞭解 CHAOSS 社群的基本概念和運作方式。此外，這本手冊還會說明 CHAOSS 社群中不同工作文化的各種程序和途徑。

技術詳細資訊：

我建議使用 Gitbook 平台來維護手冊，因為這是一項使用者友善的協作專案，可讓團隊更有效率地工作。GitBook 平台的部分功能：

  • WYSIWYG：功能強大又美觀的文字編輯器
  • Markdown：強大且高效的 Markdown 捷徑支援
  • 豐富的嵌入：嵌入影片、程式碼片段、文章、音樂等外部網路內容
  • 作家專用資訊主頁：提供支援視覺編輯的作家專用智慧型資訊主頁
  • 草稿：草擬新變更並以非同步方式協作
  • 支援留言：討論及查看草稿變更
  • 追蹤寫作記錄：追蹤所有內容。查看及還原變更
  • 深入分析：也支援深入分析，追蹤流量、評分和內容品質
  • 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 Platform 中的機構設定。圖片範例：shorturl.at/GNQR4

GitBook 空間會透過我們自己的 CDN 提供，並預設啟用 HTTPS。憑證是由 Let’s Encrypt 核發

支援的網域：

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

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

整合 GitHub 的功能非常容易使用：如果有人變更 GitBook 上的內容，他們的編輯內容就會推送至 GitHub 存放區。相反地，推送至 GitHub 存放區的修訂版本會匯入 GitBook 中。

設定 GitHub 整合：

  • 在 GitBook 平台的空間中，依序點選「整合」分頁標籤 >「GitHub」
  • 授權 GitBook 存取與貴機構連結的 GitHub 帳戶
  • 前往貴機構的 GitHub，建立「手冊」存放區，例如 chaoss-handbook
  • 接著，在 GitBook 平台的授權選項中，選取要連結的「chaoss-handbook」存放區。

完成這些步驟後，GitBook 會在 chaoss-handbook 存放區中新增 webhook，讓該存放區在每次變更時擷取內容。變更 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

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

使用者可透過 https://docs.chaoss.community 這個子網域存取 Chaoss 社群手冊，在使用者端會顯示如下：

  • Mattermost 手冊 - https://handbook.mattermost.com/
  • Linux Foundation Community Bridge 說明文件 - 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 社群方式」專欄

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 日)

  • 關於 Outreachy 指南的草稿

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

  • 緩衝時間；精修及改善整份文件

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

A.) 第 16 週：

  • 草擬專案報告
  • 填寫專案評估

社群互動

1.) 與社群互動及討論。

我自 2020 年 4 月起，持續在 CHAOSS 社群上衝浪，並與社群成員和我的特定專案導師( Georg Link 和 Armstrong Foundjem) 相關的各種討論互動。其中一個引起社群成員更大興趣的討論主題是「建議使用 Gitbook 作為社群手冊的平台」，可在 CHAOSS 存檔的電子郵件討論串中找到，討論串名稱為「建議使用 Gitbook 作為社群手冊的平台」。我也會參加社群每週的電話會議，以便向社群提供最新資訊。

2.) 你們如何收集這項專案所需的資訊？

由於這個專案需要設定社群全體手冊，因此我們會向社群成員收集和討論手冊中必須存取的資訊。如上方所述，我會在社群連結期間討論並收集必要資訊。

我會根據 CHAOSS 研究各個部分，並持續在郵寄清單上發布相關主題。我會根據需求，向導師和社群提出問題，以便釐清疑問。

為提供清楚的討論，我也會加入每週通話。

3.) 你打算如何向社群說明進度，以及在專案期間遇到的任何問題或疑問？

為了保持彈性和透明度，我會嘗試透過郵寄清單討論來提出疑問。

我會將每週的進度以網誌文章的形式分享，其中會納入 Scrum 文件和面臨的挑戰，並在社群電子郵件名單上分享，以便觸及開源組織中的更多觀眾。

我也會參加每週的社群電話會議，針對主要問題提出適當的建議和討論。

我還打算建立 Trello 看板，列出可執行的每週工作。這樣導師就能透過這個看板，清楚瞭解目前的問題和正在處理的功能。

4.) 如果無法全心投入專案，但導師沒有動靜，你該怎麼做？

我認為導師的角色是引導學生走向正確方向，而非向學生解釋每個迴圈的細節。研究和實施專案是學生的唯一責任。因此，我只會在萬不得已的情況下，向導師尋求協助。

不過，如果在需要協助時，導師不在身邊/忙於其他事物，我會轉而將問題分享給 CHAOSS 社群。我相信別人能協助解決遇到的任何問題。我也會在 dev.to 等線上論壇/開發人員社群中分享這個問題

此外，我會嘗試參與 CHAOSS 社群每週的電話會議，以便詢問疑問。