Linux Foundation 專案

本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。

專案摘要

開放原始碼組織：
Linux Foundation
技術撰稿人：
jaskiratsingh2000
專案名稱：
CHAOSS：製作《CHAOSS》社群手冊
專案長度：
標準長度 (3 個月)

Project description

專案簡介：

目前，CHAOSS 社區內的工作團隊已有自己的工作方式，並記錄了不同程度的個別程序。工作團隊包括通用指標 WG、多元與包容 WG、演化、風險及價值工作團隊，他們建立了自己的參與和工作方式，並適應不同的溝通和工作文化。這類以指標為依據的工作團隊具有不同的重點領域和背景，這些領域屬於適當的工作團隊，可引進相關的工作團隊進行各項研究和發展。此外，也知道引導新進者和現有貢獻者的程序正確，但可能不知道如何參與，或為各自工作所需採取合適的做法。

因此，CHAOSS 社群中的事物並沒有標準化。因此，為瞭解整個社群中工作文化的正確流程和基本基礎知識，社群手冊的目標，是集中彙整重要資訊，並將整個 CHAOSS 專案的某些部分標準化。關鍵資訊和標準化部分主要側重於為 CHAOSS 設定社群成就的協議、新加入者如何參與並跟上社群的基本概念，以及新手或現有成員在成為 CHAOSS 社群時必須採取哪些流程和途徑。

手冊應提供說明手冊，讓現有或新進社群成員知道如何在 CHAOSS 專案中完成工作。這項專案涉及一個創意元件，用於收集和整理手冊的內容，以及定義如何表示手冊的技術元件。

他們的需求

「社群手冊」是一份文件，定義社群的主要政策和程序，並概述社群的使命、價值觀和行動。

本手冊將為新加入的社群成員提供清楚的介紹和說明。目前，GitHub 存放區提供了 CHAOSS 社群手冊，需要更新和重構為新使用者和現有社群使用者更多資訊。因此，這份《CHAOSS》社群手冊將為新手和現有社群成員帶來以下好處：

  • 彙整與統整 CHAOSS 社群的政策，集中彙整所有資訊
  • 說明社群的介紹、使命、願景和領導力
  • 瞭解 CHAOSS 社群實踐
  • 貢獻指南
  • 定義專案工作流程
  • 概述 CHAOSS 社群文化
  • 一般常見問題
  • 輔導服務

專案說明：

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

  • 引言
  • CHAOSS 社群參與
  • 導向主管的學習路徑
  • 術語
  • 貢獻規範
    • 開發人員
    • 設計人員
    • 寫入者
    • 行銷人
  • 指標
  • CHAOSScon
  • CHAOSScast
  • 會議影片
  • 一般常見問題
  • 指導
    • Google Summer of Code
    • 外聯
    • Google 文件季別

專案淘汰項目詳情

1.) 簡介：

本節將擔任《CHAOSS 社群手冊》第一頁，其中包含手冊的詳細資料、總覽和使用方式。以下是各項目的說明：

A.) 其中包含歡迎訊息，以及 CHAOSS 社群的簡短說明，有助於說服讀者閱讀手冊。另外，我也會附上 https://chaoss.community/chaoss-photo-Album/ 拍攝的圖片美術拼貼，主要展示社區內的各種動向。 B.) 這個頁面也會提供所有部分的詳細資訊，每一行說明都有一行說明，並說明各部分以及適當的連結。 C.) 《手冊使用情形：手冊使用情形》已經在這裡( shorturl.at/cqQU6 ) 中了，但我將重構並重構現有的手冊使用情況，包括《Furbook of the book》(手冊的流程) 將包括使用者想要新增、移除或討論手冊相關問題時的情況。後續可能會追蹤手冊相關問題的溝通方式)。手冊指南(包括在社群和範圍內的用途)、對手冊的貢獻 ( 包括如何使用存放區進行變更、製作 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 中加入流程的詳細資料與說明程序，是比較合理的做法。手冊中包含下列資訊：

A.) 主辦委員會的詳細資料：其中會說明參與 CHAOSScon B. 組織委員會的程序。)提案來電管理：包括管理作者註冊、提交提案與文件、審查以及核准程序。 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 Summer of Code、 Eligibility Eligibility，以及 Google Summer of Code 中 CHAOSS 社群的參與方式。這個部分還包含提案範本，可供使用者草擬提案、角色和職責。此外，現有社群成員也可透過這些資訊瞭解成為機構組織管理員和導師的教學方法。

  1. 外聯：

本節將說明推廣計畫、資格條件，以及 Outreachy 中 CHAOSS 社群的參與方式。其中列出職務及職責，包括成為機構組織管理員和導師的進程。

  1. Google 文件季：

本節將說明 GSoD、資格條件，以及 GSoD 中 CHAOSS 社群的參與方式。其中將包含各項角色和責任，包括成為機構管理員和導師的職責。

專案預期成果：

手冊在任何社群中都扮演著重要的角色。同樣地，這份 CHAOSS 社群手冊也能為 CHAOSS 社群提供更有條理且詳盡的文件。不論是新加入社群的新手，還是社群中現有成員，都能輕鬆瞭解 CHAOSS 社群的基礎知識和作用。 此外，本手冊將為 CHAOSS 社群中的不同工作文化設立各種不同的流程和途徑。

技術詳情：

我提議使用 Gitbook 平台維護手冊，因為這個 Gitbook 平台容易使用，能讓團隊提高工作效率。GitBook 平台的部分功能：

  • WYSIWYG：功能強大但簡單易用的文字編輯器
  • Markdown：強大且高效的 Markdowns 快速鍵
  • 豐富嵌入：嵌入影片、程式碼片段、文章、音樂等外部網路內容
  • 作家資訊主頁：提供適用於作家的智慧型資訊主頁，支援圖像編輯功能
  • 草稿：草擬新變更並以非同步方式協作
  • 支援註解：討論及審查草稿變更
  • 追蹤寫作記錄：追蹤所有內容。查看及還原變更
  • 深入分析：同時支援有關追蹤流量、評分和內容品質的洞察資料
  • GitHub Sync：保留工作流程，並將文件與 GitHub 保持同步
  • 自訂品牌宣傳：自訂網域、自訂標誌、字型、顏色、主題和標題等

以下幾張圖片可幫助你快速瞭解這個平台

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

-- 手冊將存放在何處？

手冊將託管於 GitBook 本身，其中 GitHub 提供適當的自訂網域、常見錯誤及搜尋引擎最佳化機制。

自訂網域： 如果 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 手冊存放區，允許它在對存放區所做的每次變更時擷取內容。變更 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 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 日)

  • 草稿「The CHAOSS Community Way」部分

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

  • 草擬「主管階層導向」部分
  • 草擬「術語」部分

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

  • 草擬社群藍圖
  • 草稿設計貢獻指南

E.) 第 9 週 (10 月 12 日至 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 日 - 29 日)

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

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

A.) 第 16 週：

  • 草擬專案報告
  • 填寫專案的評估結果

社群互動

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

好吧，我從 2020 年 4 月就在 CHAOSS 社群中四處瀏覽，也經常與社群成員和特定專案導師( Georg Link 和 Armstrong Foundjem) 相關的討論。被提振的是，社群成員更熱衷的討論就是「提議將 Gitbook 做為代管社群手冊的平台」，而且可以在 CHAOSS 封存郵寄清單討論串中找到，其中名稱為「Proposing Gitbook」做為代管社群手冊的平台。我也持續參加社群每週通話，因此會分享許多社群的最新消息。

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

由於這項專案需要設定社群範圍手冊，以便社群成員收集和討論其中有的資訊。如同我提議在上方安排時程，這樣我就能討論及收集社區合力期間所需的資訊。

我會依據 CHAOSS 對各個部分進行研究，並且持續處理郵寄清單上的討論串。我將根據相關要求，試著向導師和社群提問釐清問題。

為了方便討論，我也會參加每週通話。

3.) 您該如何向社群保持學習進度，以及在計畫過程中遇到任何問題或疑問？

但為了保持靈活性與資訊透明度，我會透過郵寄清單討論表達疑慮。

我將以網誌文章形式分享每週進度，內容包括流浪記錄相關文件和所面臨的挑戰，並分享在社群郵寄清單中，以便觸及更多開放原始碼組織內部的目標對象。

我會每週參與社群通話，針對主要議題取得適當的建議和討論。

此外，我也打算製作 Trello 白板，列出每週可進行的任務。接著，導師可以透過這份主面板，簡明扼要地釐清目前面臨的問題和功能。

4.) 如果專案遇到困難，且導師還沒解決，你該怎麼做？

我認為導師的職責是引導學生朝正確的方向邁進，而不是逐一說明每個循環的角落。研究與執行這項專案是學生唯一的責任。請記住，我只有在不得已的情況下，才會嘗試取得導師的協助。

但如果導師沒有在場或忙到需要協助，我接下來會到 CHAOSS 社群分享我遇到的問題。我相信會有專人能協助我解決遇到的任何挑戰。我也會將問題分享到線上論壇/開發社群 (例如 dev.to)

此外，為了有疑問，我會試著每週都會撥打 CHAOSS 社群的電話求助。