CERN-HSF 專案

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

專案摘要

開放原始碼組織：
CERN-HSF
技術文件撰稿者：
SabitaR
專案名稱：
重構及簡化 Allpix Squared 說明文件
專案長度：
標準長度 (3 個月)

Project description

概觀 我選擇 CERN-HSF 的 Allpix Squared 專案，主要有兩個原因：

  1. 技能建立：這個專案的現有文件內容完整，且整合了多種內容格式。透過稽核及重整這套完整的文件套件，我可以磨練資訊架構和寫作技巧。此外，我還不太懂專案領域，也就是所謂的專案領域，這項挑戰讓我有機會磨練開發人員互動技巧。我認為，只要技術作家進行必要的背景研究，並提出正確的問題，就能處理開發人員的意見，並為各層級的使用者提供實用的內容。這項專案將讓我測試這個理論！

  2. 技術知識： 這個專案需要使用 Hugo，這是我要學習的工具之一。我期待學習 LaTeX-Markdown-Hugo-GitLab-CI 工作流程。

在技術作家探索階段，我曾簡短地與專案導師互動，並熟悉現有的文件套件結構。我還建立了一個示範網站 (https://ap2-demo.netlify.app/)，以測試是否能在 Windows 電腦上正確設定 Hugo 和 Docsy。我可以將網站部署至 Netlify，但無法將其部署至 Gitlab 頁面。為了讓這個專案維持目前的部署工作流程，我會找出將 Hugo Docsy 主題部署至 Gitlab Pages 的方法。

預期專案結果 - 結合說明文件、程式碼參考資料、教學課程與最新消息的精簡專案網站。- 經過重整及審查的使用手冊，將使用者和開發人員的內容分開，並納入先前遺漏的資訊。- 教學課程工作流程：提供操作說明文件、常見問題和常見問題的範例。

專案工具 Allpix Squared 目前的說明文件除了使用 GitLab 和 Gitlab CI 外，還使用 LaTeX、Doxygen、pandoc 和 Hugo。我和專案導師討論過，是否可以使用 MathJax 外掛程式，將內容從 LaTeX 轉換為 Markdown。如果我成功了，說明文件工作流程就會涉及 Hugo、Markdown、Doxygen、git 和 Gitlab CI。為了讓教學課程保留在同一網站/平台中，我會使用 Hugo 和 Markdown。我想瞭解是否可將 Codelab 做為教學課程的工具 (ClaaT) 使用。今年 7 月，我希望測試 ClaaT-Hugo 工作流程，並和導師討論 (如果獲選)。

專案時長 我希望在標準的三個月期限 (2020 年 9 月 14 日至 2020 年 11 月 30 日) 內完成 Allpix Squared 專案，期間我會每週花約 15 小時處理專案。如有需要，我們也會提供指導會議及相關電子郵件。我也會遵守 GSoD 的社群互動和專案定案時程。

專案工作 以下是我打算如何針對現有的 Allpix Squared 文件套件，實作我提出的更新建議： 1. 研究、討論及探索選項 (2020 年 8 月 17 日至 9 月 13 日)： - 瞭解專案要求 - 安裝 Allpix Squared 軟體，找出目前文件中缺少的資訊 (如有)。 - 要求必要憑證。 - 為 Allpix Squared 的不同使用者建立使用者工作流程 - 依使用者角色分類內容 - 確認將 LaTeX 檔案轉換成 Markdown 的影響 - 整合來源存放區，或瞭解如何使用多個 Git 存放區 - 補充資訊作者：測試 CLaaT 是教學快速/文件貢獻者專用的快速參考資源 - 社群指引要點：

  1. 重新架構、審查及改善內容 (2020 年 9 月 14 日至 10 月 19 日)： 每週兩項工作，每項工作約 5 到 7 小時。在這段時間內，可能會有緩衝週處理非預期的延遲或問題。

    • 將現有的內容和使用者分類納入考量
    • 為不同使用者規劃及測試重構內容工作流程
    • 取得及改善缺少的內容
    • 將 LaTeX 檔案轉換為 Markdown
    • 完成使用手冊和開發人員指南目錄
    • 產生使用者和開發人員指南的 PDF 檔案
    • 額外獎勵：從範例和問題中結構化教學課程內容
    • 額外獎勵：設定教學工作流程，提供操作說明範例 時間表：5 週 (文件開發階段)

  2. 建立網站 (2020 年 10 月 19 日至 11 月 30 日)： 每週 1 至 2 項工作，每個工作約 5 至 7 小時。這個時間表包含緩衝週，可用於排解問題並微調最終輸出內容。

    • 瞭解及測試發布工作流程
    • 使用 Hugo 和 Docsy 建構網站架構
    • 測試如何使用 Docsy 維護目前的自動部署作業和工作流程
    • 從 Doxygen 提取內容
    • 使用 LaTeX 或 Markdown 內容開發使用者手冊、開發人員指南和教學課程
    • 完成專案網站的外觀和風格 (標誌、顏色、範本、版面配置、連結、可用性和 Gitlab CI/CD) 時間軸：6 週 (文件開發階段)