本页面包含“Google 文档季”接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- DIPY
- 技术文档工程师：
- Areesha Tariq
- 项目名称：
- 大体结构调整和以最终用户为中心
- 项目时长：
- 标准时长（3 个月）
Project description
我是一名软件工程师，具备技术写作方面的专业知识。我在撰写优质软件文档、用户指南、手册和项目说明方面拥有 4 年以上经验。我住在巴基斯坦伊斯兰堡（时区：UTC + 5）。目前，我在 Outreachy 团队当实习生，工作经历将一直持续到 8 月 18 日。 我曾在 OpenELIS Global 组织担任技术文档工程师，参与了 Google 文档季。原始文档是法语的，内容有限且已过时，因此我编写了内容丰富的英文最终用户文档，并进行了更新。2020 年 5 月至 8 月左右，我入选 Perl & Raku 的 Outreachy 组织，担任 Open Food Facts 服务器的后端开发者。除了后端开发之外，此实习职位的主要任务之一就是以 POD 格式为模块和功能创建文档。 去年，我为一些开源项目做过贡献，后来参加了 Google 文档季，开始进入开源领域。今年，我入选了 Outreachy，致力于支持开源和免费软件的多元化。我的 Outreachy 项目托管在 GitHub 上，我对 Git 很有信心，而且自 3 月份以来，我一直在为 Open Food Facts 和 Mozilla Fenix 做贡献。我是一名 Linux 用户，过去 3 年多，从那时起我就一直在使用终端命令。
我使用的文档工具和语言包括 Sphinx、阅读文档、Markdown。 我喜欢这个创意，并希望将其付诸实践，因为我拥有相关经验，并且乐意利用自己的知识和技能为 DIPY 做贡献。我在数字图像处理、计算机视觉和机器学习领域拥有丰富的经验。这有助于我更好地了解神经影像，并帮助撰写相关文档。我在医疗领域拥有丰富的经验。我开发了一个面向医生、患者、实验室、救护车司机的医疗网站。我开发了另一个供医生、患者、护士、实验室助理和研究人员使用的系统。这有助于我创建更易于受众理解的文档。
我仔细阅读了 DIPY 的文档，并记下了文档中的一些缺陷。文档中有多个漏洞，我都计划加以改进。 文档的当前状态： 文档缺少特定的结构和设计 它可能繁琐而耗时，特别是对于新用户来说，导航很困难 用户可能会发现很难从指南中获取信息 文档的内容需要改进 作为新用户，我发现很难访问用户指南和开发者指南。需要重塑文档，使用户所需的信息易于访问 文档缺乏一致性
我计划执行以下操作：
为文档定义特定的结构和模板 重塑文档，以便用户轻松浏览和查找所需信息 制作路线图或工作项列表，以便在后续文档工作中吸引社区 定义用户指南和开发者指南的模板 定义贡献指南模板 重写、重构和更新用户指南、开发指南和贡献指南（有助于和激励新用户为项目做贡献） 添加非文本内容
用户指南：
作为用户指南，我将重点使用简单明了的语言来帮助用户理解最复杂的系统。为了提供更好的用户体验，应避免使用新用户可能不知道的术语、首字母缩写词和其他内部信息。我还将重点利用视觉内容（包括图片、带注释的屏幕截图、图形和视频）来快速向用户展示系统的运作方式。好的文档需要包含标题和子标题的层次结构，以便用户了解每个部分将显示什么内容。该层次结构应遵循逻辑流程，帮助用户学习如何以最有用的方式使用系统。此项目的主要目标是创作无障碍内容。 所有文档和指南将采用一致的风格。必须在多个文档中使用一致的字体和互补色。我将确保用户可以访问该组织的更多资源，了解如何通过这个系统取得成功。
开发者指南：
开发者指南包含大量指导和参考资料，可帮助开发者为 DIPY 的源代码创建贡献。它会尝试列出可供您使用的各种选项，以便您根据要实现的目标使用正确的方法。 开发指南需要重塑和调整结构。我将重新编写开发者指南的内容。构建依赖项、贡献指南、样式指南、编码规范、文档指南、安装开发环境、调试、测试指南和相关内容都将包含在内，并且可供开发者轻松访问。 当热切期盼的新贡献者急于去您的项目做出第一次开源贡献时，他们会以贡献准则作为指引。因此，这些指南应通俗易懂、通透且友好。贡献指南是一种实用文档，用于宣传人们该如何为开源项目做贡献。为项目做贡献应尽可能简单、透明，包括： 提交修复方案 报告错误 成为维护人员 讨论代码的当前状态 提出新功能建议
TEMPLATE
这是一款可用于投稿指南的模板。您可以按照文档的要求对其进行修改，添加或删除各个部分。
为 DIPY 贡献力量
- 欢迎备注
TOC
行为准则
- 我们的标准
- 有助于营造积极环境的行为示例
- 不可接受的参与者行为示例
- 我们的责任
- 项目维护者的职责
- 范围
行为准则范围
我需要知道什么帮助？
如果您想要帮助我们做出代码贡献，我们的项目会使用 [插入项目使用的编程语言、框架或工具的列表]。如果您尚未准备好贡献代码，也没关系！您还可以查看文档问题 [link to the docs label or tag on your Issue Tracker] 或我们存在的设计问题 [如果您的项目跟踪的是设计问题，则 [link to design label or tag on 问题跟踪器]。 如果您有兴趣为代码贡献力量，并希望详细了解我们使用的技术，请查看下面的列表。 列出资源（教程、视频和图书）的项目符号列表，以便新的贡献者能够了解用户需要了解哪些信息来为项目做贡献。
设置开发环境
在本部分中，我将添加安装过程和需要安装的依赖项。通过运行以下命令安装 $project：install project
- 源代码：github.com/$project/$project
- 问题跟踪器：github.com/$project/$project/issues
如何贡献自己的力量
如何报告 bug
- 提交 bug 报告之前
- 如何提交（良好）错误报告？
如何提交更改
- 拉取请求协议
- 团队回复
- 响应速度
如何申请增强功能
- 提交增强功能建议之前
- 如何提交（良好）增强建议？
您的第一项代码贡献
- 新手问题
- 帮助所需的问题 #### 拉取请求
- 创建拉取请求的流程
- 验证是否所有状态检查均已通过。
如果状态检查失败，该怎么办？
- 编写测试
- 测试覆盖范围
风格指南
- Git 提交消息
- 标准样式
支持
如果您遇到问题，请告诉我们。如需帮助，您可以通过以下邮寄名单向我们提问：project@google-groups.com、IRC 聊天或 [列出您的项目使用的任何其他通信平台]。
许可
此部分会介绍项目许可。
投入时间和沟通：
我每周会留出超过 45 小时的工作时间，但如果发生任何意外，我会在周末提供补偿。在社区凝聚期期间，我将与导师讨论沟通方式，并最终确定每周的会议、方式和时间。我会及时向导师提供有关我的工作的最新动态；还会通过电子邮件与导师分享我的工作详情。我更喜欢使用 TeamViewer 进行沟通，因为该工具易于使用，具有共享屏幕等众多功能。