本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- CERN-HSF
- 技術撰稿人：
- 艾雅德
- 專案名稱：
- Rucio - 翻新 (重構及重寫) Rucio 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要：Rucio 架構的開發目的，是為了管理和整理分散在不同資料中心的大量地理分散科學資料。這個架構提供分散式資料復原和自適應複製等功能，具備高度可擴充性、模組化和可擴充性。這類服務的說明文件來自各種背景，且在存取時也各有不同。因此，這類服務的說明文件應簡化使用者採用和使用服務的流程，同時也能提供常見問題的參考資訊，協助排除問題。
如未提供這類文件，就無法有效運用這些工具。這可能會導致支援成本增加，並對產品的企業形象造成聲譽風險。畢竟說明文件是一種溝通方式。因此，請務必將通訊內容封裝在可管理且可存取的架構中，並配合適當的版本控制，確保通訊內容能順利傳達。
在本文撰寫期間，Rupio 架構曾用於滿足 LHC 對 ATLAS 和 CMS 實驗的高能量需求。它也用於支援 LHC 以外的多元科學社群需求，例如天文物理學。因此，說明文件必須盡可能提供相關資訊，並方便使用者存取。在這項專案的協助下，CERN 希望讓使用者享有順暢的體驗，同時透過集中式檢視畫面存取所有相關說明文件。
目前狀態： 截至目前，使用者說明文件散布在不同位置，且格式多元，包括科學論文、readthedocs.io (含程式碼來源)、Google 雲端硬碟、GitHub、DockerHub 或 Wiki。多個來源會導致追蹤版本和說明文件正確性的問題。此外，分散式說明文件模式會對特定用途的導覽和相關資訊顯示造成重大障礙。特別是在 Wiki 的情況下，所提供的特定實驗所提供的資訊，同樣可能也適用於位於相同或其他來源的其他情況。不過，由於缺乏整合和適當的連結，這些資訊無法充分發揮效用。
您提出的使用者說明文件為何比目前的版本更優？考量到多面向的問題，下方提出的模型可解決導覽、版本控制、追蹤和顯示文件的障礙，詳情如下：
重整說明文件旨在簡化使用者導覽過程。搜尋資訊時，他/她不必再鑽牛角尖，因為資訊會分類/標示，以便簡化搜尋流程。從管理角度來看，重構可讓您依需求自由分類，因此版本管理和追蹤作業會變得簡單許多。將所有重新結構化的文件集中管理，可確保使用者不必參考多個來源，就能查看所有資訊。
分析： 詳閱需求簡報並與指導團隊進行對談後，我對 Rucio 說明文件目前狀態的推論如下：
有六個主要的說明文件來源： - Google 雲端硬碟連結：https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
閱讀由 Sphinx 技術提供的說明文件 程式碼連結：https://github.com/rucio/rucio ReadtheDoc 的連結：https://rucio.readthedocs.io/en/latest/
DockerHub 連結：https://hub.docker.com/u/rucio
GitHub 連結：https://github.com/rucio/rucio
維基 連結：https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
科學文章 連結：https://arxiv.org/abs/1902.09857
這些來源的說明文件採用不同格式。舉例來說，Google 雲端硬碟的說明文件以簡報和文件的形式呈現，GitHub 的檔案則主要以 reStructuredText 標記語言呈現，等等。由於缺乏版本控制和追蹤功能，導致多個來源會發布重複的資訊。資訊的標示/分類方式不一致。因此，搜尋時必須具備相關經驗和專業知識。
由於格式和來源眾多，因此我們建議使用 mkdocs 重新建構資訊並集中管理。為了更加瞭解這些工具，我研究並熟悉相關工具的用法。
判決結果：現有的文件並未結構化，且散落各處，也沒有適當的連結。也缺乏格式統一且統一的格式。導致使用者必須額外花費心力進行搜尋。這類差距也會對管理員/維護者/主管造成不必要的壓力，導致難以維持以社群為導向的維護與更新說明文件方式。使用者和貢獻者的體驗會大幅降低，且會重複
建議文件結構：
在仔細分析需求後，我決定透過重新設計的文件模型解決主要問題。
重新設計的模型示範圖片已附在下方，每份文件都會歸類至下列 7 個類別：
- 關於
- 開始使用
- 概念
- Rucio 介面
- 工作
- 教學課程
- 進階專業知識
當然，還有一些改善空間，例如新增連結，這是我希望在完成這項計畫後著手的項目。超過 1000 名活躍使用者會存取 Rucio 上的 500 PB 資料，因此建議重新調整說明文件的架構，應該就能大幅減少使用者需要使用支援電子郵件名單的情況。目標是降低點擊率，並藉由分類和標籤輕鬆提供說明文件，進而提升使用者體驗。使用者/作業人員/管理員只要點選 3 次，就能找到所有相關資訊。
原型設計連結：https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing
專案目標： - 分析並刪除來自不同來源的多餘資訊，也就是每項資訊都應來自單一可靠來源。- 透過標記和分類，將現有文件重新架構為不同的部分 - 將重新架構的文件遷移至以 mkdocs 為基礎的集中檢視畫面 - 重新格式化/匯入因檔案格式限制而無法遷移的文件 - 設定社群驅動的文件修改作業，確保填補任何缺口，包括連結、資訊更新或錯誤修正。
這個系統的基礎架構已就位，但我的模型會透過適當的貢獻與治理指南和相關文件，改善現有系統。此外，我認為可以整合 GitHub 專案看板，追蹤問題和專案的整體健康狀況。
時間表： - 8 月 16 日前 --> 熟悉目前版本的說明文件和 Rucio --> 學習新技術和技術寫作技能，以利於在專案期間執行 --> 協助解決 GitHub 上回報的說明文件問題 (如有)
社群連結 (8 月 17 日至 9 月 13 日) --> 設定通訊管道和時間，以便因應時區差異 (浦那的時間比臺灣快 3 小時 30 分鐘) --> 找出主要問題，以便精進目標 --> 透過對話進一步瞭解社群、機構和架構。 --> 與導師和機構的其他重要成員共同評估所提說明文件結構，瞭解實施的可行性。--> 完成建議功能，以及可能需要對現有文件進行的任何其他修改。
說明文件期間 (9 月 14 日 - 11 月 30 日) 根據我在此處提出的建議格式，我已提供說明文件期間內預計達成的主要里程碑。
--> 里程碑 #1：分類與標記 ETC：2020 年 9 月 28 日 整合現有的說明文件並加上標記，可大幅簡化重整與裁撤程序。
--> 里程碑 #2：分析、刪除及重整 ETC：2020 年 10 月 19 日 在里程碑 #1 中分類的文件會進行分析，找出重複和多餘的資訊來源。如專案資訊所述，我們會針對所有可用資訊，指定一個可靠資訊來源。
--> 里程碑 #3：集中化與調整格式： 預計到達時間：2020 年 11 月 9 日 說明文件經過適當剪接及重新編排後，我會先重新設定格式。由於來源各異，格式也不同，因此必須先轉換成適當的格式。完成後，集中化程序就會變得更簡單。
--> 里程碑 #4：設定追蹤板 + 治理/貢獻相關文件 ETC：2020 年 11 月 23 日 這個階段旨在確保在專案完成後，文件持續保持更新。制定規範並建立專案委員會，有助於管理員有效地徵求社群貢獻內容並追蹤相關進度。
--> 專案評估 (11 月 30 日 - 12 月 5 日) 提交一份專案報告，並為我的導師進行評估 撰寫並提交一份報告，說明我參與「Google 文件」之季的情形
為什麼要進行這個專案？我認為，透過編寫完善且有版本控制的說明文件來補充程式碼，是讓程式碼獲得更廣泛採用和更妥善運用的唯一方法。就我個人而言，我很欣賞 CERN 在物理學不同領域開創先進研究的做法。考量到這類實驗期間處理、轉移及產生的資訊規模，我一直很好奇，資料是如何管理，以供參考及日後在機構內使用。很榮幸能為這個架構改善文件，這個架構一直以來都為科學研究和發現提供強大的支援。
為什麼我適合負責這個專案？除了符合必要條件外，我相信自己是這個專案的合適人選，因為：
我正在修改現有的 Kubernetes 說明文件。這些貢獻讓我成為 1.19 Kubernetes 版本週期的「Release Docs Shadow」，負責有效維護及升級版本中新增功能的說明文件。我認為優質的說明文件是優質產品/服務的基礎。無論是程序還是技術知識，條理分明、簡單明瞭且易於取得的資訊，對於提升採用率和提高使用率而言會是不利因素。 我一直在職涯中使用資料驅動的分散式系統，因此我相信自己最能瞭解這類系統的相關文件中，複雜的相關規定。我本身就是使用者，我很熟悉文件寫錯/不正確的問題。在調整架構時，我也要小心謹慎。