本页面包含“Google 文档季”接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Kolibri
- 技术文档工程师：
- StephDix
- 项目名称：
- Kolibri 生态系统文档样式和工作流规范
- 项目时长：
- 长期投放（5 个月）
Project description
概要
本文档详细介绍了对于 Kolibri 生态系统项目的 Learning Equality 文档记录信息，如何实现样式准则和工作流管理。
概览
我的提案包含四个阶段。在第一阶段，我将按照软件开发中的 LE 概念和风格指南完成 LE 文档风格指南，并提供无障碍功能指南、文案和格式建议。在第二阶段，我将对 ReadTheDocs 和 GoogleDocs 文档进行质量审核。审核计划整合了核对清单的使用，以评估对风格指南的遵从情况。这些核对清单有助于记录发现结果并对文档进行更改。在第三阶段，我将负责修改 ReadTheDocs 和 GoogleDocs 文档中模板的结构、外观和风格。我将在 Google 云端硬盘中创建一个模板和图片库，用于标识主文档类型的每个模板类别，以便在即将进行的实现中重复使用。我将帮助完成这一任务：创建模板来提交文档问题，以便在拉取请求审核中轻松识别问题。最后，我将编写一份贡献者指南，用于为各组协作者汇总有用的资源，以提升他们访问信息的体验。
用途和范围
我们制定这项实施计划的目的是提升最终用户使用 Kolibri 文档的体验，并帮助团队成员和贡献者制作更好的文档，并在社区中积极开展协作。 此实现适用于 Kolibri 生态系统中的 ReadTheDocs 和 Google 文档文档的子集。
受众群体
实现者、管理员和最终用户的主要受众是 Kolibri 文档最重要的使用者。由团队成员和协作者组成的次要受众群体，用于制作和使用 Kolibri 文档。
目标
Kolibri 生态系统文档的风格指南和工作流程系统要求用户： 使用易于访问的语言和一致的布局构建易于理解的文档。 按照文档记录，妥善维护质量实践。 确保在不同文档渠道之间轻松访问信息。 加强 Kolibri 开源社区的协作举措。
Sources of information
我的信息来源有 Kolibri、Kolibri Studio、Kolibri Development RTD 文档和 Google 云端硬盘中的 Kolibri 工具包。
优秀的 Radina Matic 对提供热身活动和针对特定项目的活动大有帮助。她对组织的“Guidelines”和“Guides”概念的见解，并介绍了有一份贡献者指南的存在，帮助我整理自己的想法和起草结论。
软件
我将在 Google 文档中编写风格指南草稿。此文档平台非常适合在准备好发布时进行迭代。对于质量检查审核，我将使用 Google 表单处理和评估文档。电子表格会存储表单回复，以便控制文档。 我将使用 GitHub 重构 RTD 文档。我使用过 Git、Gitkraken、GitHub 和 Gitlab。我具备 Markdown 方面的实践知识，还熟悉了一些 ReStructuredText。我打算贡献力量修复文档，以便继续学习语法。我将使用 Sharex 传输图片和 GIF。我喜欢这个工具，因为它能以不同的输出格式呈现。 我将使用图表来制作示意图和图片版本。Diagrams 软件与 Google 文档、Google 云端硬盘和 LibreOffice 完美集成。 文档状态 在探索阶段，我修改了 Kolibri 的大部分文档。我发现了语法错误、拼写错误，布局、排版和图片使用不一致，以及项目的大多数文档中令人困惑的文档路径。例如，在 Kolibri 的用户指南中，问题排查部分是子主题，而非主题。此信息非常重要，可协助最终用户从目录中访问这些信息。第二种方法是，使用搜索栏和目录树展开其他主题并找到问题排查文章。
如需访问“Troubleshooting”（问题排查）部分，您必须搜索相应部分或展开“Manage Kolibri”（管理 Kolibri），确认文档中已包含“Troubleshooting”（问题排查）功能。 指南与指南 对于此项目提案，我分析了两份文档： LE Kolibri 用户文档样式指南和 LE 翻译指南。 在 LE Kolibri 指南中，我根据自己提议的主题大纲和文档计划以及其他一些需要改进的方面提出了建议和意见。 对于 LE 翻译指南，我根据自己的建议和样式指南中的现有惯例更改了格式和样式。 在分析过程中，我最主要关注的是归类为“指南”和“指南”的文档之间存在误解。
成果
除了建议和意见之外，我还对 LE 翻译指南进行了质量检查，并提供了一份初步表单，我在质量检查审核任务中详细说明了该表单。 以下是通过评估获得的一些最后的意见： ICU 语法 .js 网站的链接损坏 创建这些准则所用的格式不正确。 本文档为指南，而非指南。 排版不一致。 标题和标题使用错误、 措辞不当和缩写词的不当使用。 替代文本使用不当。 反复声明/ 说明。
这两个文档的发现结果都包含在此提案的“交付成果”中。
项目特定任务
- LE 用户文档风格指南建议（注释）
- 提供新样式和格式的 LE 翻译指南。
- 主题概要
- 项目时间表
- 文档任务