本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 欧洲核子研究中心 (CERN-HSF)
- 技术文档工程师：
- SabitaR
- 项目名称：
- 重构和简化 Allpix Squared 文档
- 项目时长：
- 标准时长（3 个月）
Project description
概述 我之所以选择 CERN-HSF 的 Allpix Squared 项目，主要有两个原因：
技能培养： 此项目的现有文档很全面，并且集成了多种内容格式。负责审核和调整这个庞大的文档套件，帮助我提升信息架构和写作能力。 此外，项目领域（粒子物理学！）对我来说还不熟悉。它挑战我提升自己的开发者互动技能。我认为，如果我们进行必要的背景调查并提出合适的问题，技术文档工程师就可以处理开发者输入的内容，为任何级别的用户呈现实用内容。这个项目将检验这一理论！
技术知识： 这个项目需要使用 Hugo。Hugo 是我的学习资源列表顶端的工具。期待学到 LaTeX-Markdown-Hugo-GitLab-CI 工作流程。
在技术文档工程师探索阶段，我与项目导师进行了短暂的交流，并熟悉了现有的文档套件结构。我还构建了一个演示网站 (https://ap2-demo.netlify.app/)，以测试我能否在 Windows 计算机上正确配置 Hugo 和 Google Docsy。我能够将该网站部署到 Netlify，但无法将它部署到 Gitlab Pages。为了让此项目保持其当前的部署工作流，我会找到一种方法来将 Hugo 文档主题部署到 Gitlab Pages。
预期的项目成果 - 一个精简的项目网站，整合了文档、代码参考、教程和资讯。 - 一份经过调整并经过审核的用户手册，分离了面向用户和开发者的内容，加入了之前缺失的信息。 - 一个教程工作流程，基于可用的方法文档示例、常见问题解答和常见问题。
项目工具 Allpix Squared 的当前文档使用了 LaTeX、Doxygen、pandoc 和 Hugo，以及 GitLab 和 Gitlab CI。 项目导师和我聊过可能会使用 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 用作教程的一个选项：将 CLaaT 用作教程的快速编写指南：面向贡献者的社区简短文档指南 - 面向贡献者的快速学习指南
调整内容结构、审核和改进内容（2020 年 9 月 14 日至 10 月 19 日）：每周两项任务，每项任务大约 5-7 小时。此时间表包括缓冲周，以处理意外延迟或问题。
- 检查现有内容和用户分类，充分考虑用户工作流程
- 针对不同用户概述并测试重构后的内容工作流
- 获取缺失内容并对其进行改进
- 将 LaTeX 文件转换为 Markdown
- 完成用户指南和开发者指南目录
- 生成用户和开发者指南的 PDF 文件
- 附注：根据示例和问题为教程设计结构内容
- 额外知识点：设置用于介绍操作方法示例的教程工作流 时间轴：5 周（文档开发阶段）
构建网站（2020 年 10 月 19 日至 11 月 30 日）：每周 1 至 2 项任务，每项任务大约 5 至 7 小时。此时间表包括一个缓冲周，用于排查问题和微调最终输出。
- 了解和测试发布工作流程
- 使用 Hugo 和 Docsy 构建网站结构
- 测试如何使用 Google 文档维护当前的自动部署和工作流
- 从 Doxygen 拉取内容
- 利用 LaTex 或 Markdown 内容开发用户手册、开发者指南和教程
- 最终确定项目网站的外观和风格（徽标、颜色、模板、布局、链接、易用性和 Gitlab CI/CD） 时间表：6 周（文档开发阶段）