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 Pages。为了让此项目能够保持其当前的部署工作流，我会想办法将 Hugo Docsy 主题部署到 Gitlab Pages。

预期项目成果 - 一个简洁的项目网站，集成了文档、代码参考、教程和新闻。 - 经过重构和审核的用户手册，其中将面向用户和开发者的内容分开，并包含之前缺失的信息。 - 教程工作流程，其中包含方法文档、常见问题解答和常见问题的示例。

项目工具 除了 GitLab 和 Gitlab CI 之外，Allpix Squared 的当前文档还使用了 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 周（文档开发阶段）