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