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 頁面的方法。

預期專案結果 - 簡化的專案網站，整合說明文件、程式碼參考資料、教學課程和新聞內容。- 重新設計與審查的使用者手冊，將專為使用者和開發人員區分的內容分開，並包含先前遺漏的資訊。 - 教學課程工作流程表，包含操作說明說明文件、常見問題及常見問題等範例。

專案工具 Allpix Squared 目前的說明文件除了使用 GitLab 和 Gitlab CI，也使用 LaTeX、Doxygen、pandoc 和 Hugo。 專案導師和我也曾談過，可能透過 MathJax 外掛程式將內容從 LaTeX 移到 Markdown。如果成功，文件工作流程就會包含 Hugo、Markdown、Doxygen、git 和 Gitlab CI。 為了將教學課程保留在相同網站/平台上，我會使用 Hugo 和 Markdown。我想瞭解使用程式碼研究室即工具 (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 週 (文件開發階段)