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