本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- CERN-HSF
- 技術文件撰寫者：
- 亞裡亞
- 專案名稱：
- Rucio：更新 (重組及重寫) Rucio 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
抽象：Rucio 架構旨在呈現一個檢視畫面，用於管理及整理在不同資料中心之間，大量分散各地的科學資料。這套架構提供分散式資料復原和自動調整式複製等功能，因此具備高擴充性、模組化和擴充能力。這類服務的說明文件來自各種背景，存取需求也有不同。因此，這類服務應提供優質說明文件，以簡化使用者採用的方式及運用方式，同時提供常見問題和疑難排解的參考資料。
如果沒有提供這類說明文件，效率及有效利用將造成重大阻礙。這可能導致支援成本增加，並使產品企業身分受到聲譽的風險。畢竟說明文件就是一種溝通模式。確保溝通過程已融入易於管理且容易使用的架構中，同時維持適當的版本管理功能，確保溝通管道能成功。
撰寫本文時，該公司利用 Rucio 架構，實現 LHC 的 ATLAS 和 CMS 實驗高能源需求。這個資料庫也用來滿足 LHC 以外多元科學社群的需求 (例如天體物理學)，因此文件必須盡可能相關且容易取得。在這項專案的協助下，CERN 希望透過集中檢視所有相關說明文件，讓 Rucio 使用者享有流暢的體驗，並充分運用架構。
目前狀態：截至今日，使用者說明文件散佈在不同地方，有多種格式，包括科學文章、Readthedocs.io 和程式碼、Google 雲端硬碟、GitHub、DockerHub 或 Wikis。多個來源在追蹤版本和說明文件的正確性方面造成問題。此外，在瀏覽及顯示特定用途相關資訊時，去中心化的說明文件模型會讓使用者產生巨大的阻礙。特別是在 Wikis 的情況下，特定實驗提供的資訊對於位於相同/其他來源的其他例項也十分適合。然而，由於缺乏整合和適當的連結，因此資訊可能處於閒置狀態，而且可能並未充分利用。
您建議的使用者說明文件改善的原因為何？鑒於多面向的問題，下方的模型可解決導覽、版本管理、追蹤及顯示說明文件的阻礙，詳細說明如下：
重整說明文件的目的，在於簡化瀏覽操作時應執行的事項。搜尋資訊時，他不必為了取得資訊而分類/加上標籤，因此不用在尋找兔子洞時也不用擔心。從管理的角度來看，版本管理和追蹤非常容易，因為重新建構架構能讓使用者可以依照需求自由分類。 集中管理所有重新建構的文件，是確保使用者能看到所有資訊，而不需參照多個來源。
分析： 您在閱讀要求簡介後，接著與指導團隊討論，我的 Rucio 文件目前狀態的扣款如下：
文件來源有六大來源： - Google 雲端硬碟連結：https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
採用 Sphinx 技術的 Readthedocs，程式碼提供原始碼 連結：https://github.com/rucio/rucio 閱讀文件連結：https://rucio.readthedocs.io/en/latest/
DockerHub 連結：https://hub.docker.com/u/rucio
GitHub 連結：https://github.com/rucio/rucio
Wikis 連結：https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributiondComputing
科學文章 連結：https://arxiv.org/abs/1902.09857
這些來源的說明文件採用不同的格式。舉例來說，Google 雲端硬碟提供簡報和文件形式的文件，GitHub 檔案主要是採用 reStructuredText 標記語言等等。因此，不需要版本管理和追蹤，導致在多個來源發布多餘的資訊。 資訊的標籤/分類並沒有統一。因此，搜尋時必須具備過往經驗和專業知識。
由於有各式各樣的格式和來源，他們會期望使用 mkdocs 重新建構資訊並加以集中。為了更進一步瞭解這些工具，我研究並熟悉這些工具的用法。
判定結果：現有說明文件為非結構化內容，在沒有適當連結的情況下散佈。也缺乏集中化和統一的格式。讓使用者必須投入更多心力執行搜尋。這樣的落差也對管理員/維護人員/待開發客戶造成不必要的壓力，因為難以維護社群導向的維護與更新說明文件。使用者和貢獻者的體驗大幅降低，且
建議的說明文件結構：
全面分析需求後，我決定利用重新建構的說明文件模型來解決主要問題點。
下方附上的模擬圖顯示重新結構化模型，並將每份說明文件分為下列 7 種類別：
- About
- 入門課程
- 概念
- Rucio 介面
- 工作
- 教學課程
- 進階專業知識
當然，修習計畫完成後，我們都有改善不少功能，例如新增連結。目前 Rucio 有超過 1, 000 名活躍使用者存取 500 PB 的資料，因此提議重新建構說明文件，應可大幅降低使用者不必仰賴支援郵寄清單的需求。目標是降低點擊率，並透過分類和標籤輕鬆顯示說明文件，進而改善使用者體驗。在使用者/作業/管理員人員方面，只需點按 3 次，即可掌握所有必要的資訊。
模擬連結：https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
專案目標： - 分析及刪減各種來源提供的備援資訊，例如每項資訊都應有單一可靠資料來源。 - 將現有說明文件加上標籤並分類到不同部分，重新建構架構 - 根據 mkdocs 將重新結構化說明文件遷移至集中式檢視畫面 - 根據檔案格式限製而無法遷移的格式/匯入說明文件 - 設定由社群導向修改文件，確保填補所有遺漏的資料缺漏、更新資訊或修正錯誤。
這個系統的有門檻已就定位，不過我的模型會依照適當的文件提供適當的貢獻與管理指南，進而改善現有系統。 此外，我也希望整合 GitHub 專案委員會追蹤問題和專案整體健康狀態。
時程： - 在 8 月 16 日之前 --> 熟悉目前的說明文件版本和 Rucio --> 學習新的技術和技術寫作技巧，這些技術和技術寫作在專案期間將能派上用場 --> 對說明文件問題貢獻心力 (如有)，請前往 GitHub 回報
社區凝結 (8 月 17 日至 9 月 13 日) --> 建立通訊管道和時間來考量時區差異 (Pune 要過 3 小時 30 分鐘) --> 展開對話，進一步瞭解社群、機構和架構的重大問題。 --> 評估你提出的文件結構，與顧問和其他機構組織的其他重要成員進行評估，確認實作的可行性和可行性。 --> 完成提議的功能，以及可能需要對現有文件所做的任何其他修改。
說明文件期 (9 月 14 日至 11 月 30 日) Basis 我在這裡規劃的提案格式，詳加說明我計劃在說明文件期間達成的主要里程碑。
--> 里程碑 #1：分類和標籤 預計到達時間：2020 年 9 月 28 日 製作可用文件和加上標籤時，將大幅簡化重組和裁舊程序。
--> 里程碑 #2：分析、修剪和重組 ETC：2020 年 10 月 19 日 凡是在里程碑 #1 期間分類的文件，將進行分析，判斷是否有重複內容和多餘資訊來源。如專案資訊所述，我們會針對所有可用資訊指定單一可靠資料來源。
--> 里程碑 #3：集中化與重新格式化： 預計完成時間：2020 年 11 月 9 日 只要文宣文件經過妥善修剪並重新架構，我將目標放在先重新調整文件格式。格式也不一樣，需要先轉換為合適的格式。完成這個步驟後，集中程序就能變得更加簡單。
--> 里程碑 #4：設定追蹤看板 + 有關管理/貢獻的預計到達時間：2020 年 11 月 23 日 這個階段是為了確保專案完成後，說明文件會持續更新。只要卸下準則並設定專案主面板，就能減輕行政人員的負擔，讓他們輕鬆募集社群貢獻內容，並有效追蹤這些內容。
--> 專案評估 (11 月 30 日至 12 月 5 日) 提交專案報告並評估我的導師 撰寫並報告「Google 文件」季別的參與人員經驗報告。
為什麼會設計這個專案？我認為，使用妥善撰寫且版本的文件來補充程式碼，是提升採用率和使用率的唯一方法。我個人非常著迷於 CERN 在不同物理領域的先進研究 。由於在這類實驗期間處理、傳輸及產生的資訊規模龐大，我一直想知道在機構內管理資料以供參考及日後使用的做法。針對某個架構推動一些令人驚豔的科學研究與發現，我們想提供改善說明文件，也很榮幸。
為什麼我是這項專案的負責人？除了符合必要條件以外，我確定自己是這項專案的負責人，原因如下：
我正在努力修改現有的 Kubernetes 說明文件。這些貢獻促使我在 1.19 Kubernetes 發布流程中獲選為發布文件的陰影，在 1.19 Kubernetes 發布流程中，協助有效維護及升級說明文件，瞭解發布時新增的功能。我認為優質文件是絕佳產品/服務的支柱。無論是程序或技術資訊，妥善撰寫、簡明且易於存取的資訊，都可能成為提高採用率及提升使用效率的關鍵要素。 我在整個職涯中都採用了資料導向的分散式系統，相信在瞭解這類系統說明文件的需求時，我應該能充分瞭解相關規定。一直以來，我本身就是使用者，也很熟悉文件撰寫不當/文件錯誤等陷阱，並會謹慎在重組過程中考量這類問題。