本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 维基媒体基金会
- 技术文档工程师：
- Pavithra Eswaramoorthy
- 项目名称：
- 为维基媒体的技术纪录片工作者和摄像师提供改进文档
- 项目时长：
- 标准时长（3 个月）
Project description
1. 关于我
几个月前，我开始接触开源软件，但几乎立即就被其无限的范围感到不堪重负。在努力完成数十亿个项目的过程中，我了解了 Google 编程之夏 (Google Summer of Code) 和 Outreachy 计划等开源计划。Google 文档季似乎很有趣，维基媒体基金会的项目创意激起了我的好奇心，于是我开始深入探索。
到目前为止，我的旅程充满了令人兴奋和困惑，充满了“等等，什么？”“啊，我明白了！”和“我该发表评论吗？”。维基媒体社区在每一步都竭诚为我提供支持。从修改网页到创建附加信息，我每天都能学到新东西。
正如预期的那样，申请流程是我进入开源社区的通道。这项提议的灵感来自我作为初学者的亲身经历。
2. 项目
2.1. 轮廓
此项目旨在为维基媒体上的技术文档撰写人和潜在摄像师改进文档。 一套成熟的技术文档指南有助于改进整体文档，而创建抓屏的参考有助于有效地演示软件功能。可以对这些领域的现有文档进行扩展，以便更好地为新手和有经验的贡献者提供支持。我们将采用循序渐进的方式来开发这个实用的资源网。
2.2. 交付成果
T197006 [https://phabricator.wikimedia.org/T197006] - 为维基媒体的纪录片工作者改进文档：
- 向文档/样式指南添加了提示和示例。[https://www.mediawiki.org/wiki/Documentation/Style_guide]
- 在技术文档模板和建议中添加针对特定类型的 MediaWiki 特定信息：用户指南、方法指南、快速入门指南、版本说明和自述文件。[https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
- 测试并完善关于技术文档优先级排序的指南。[https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
- 为不同类型的文档设计内容收集策略。
- 为 MediaWiki 的文档设计沟通和协作策略。
- 创建一份核对清单，以便撰写者在发布文档前根据该核对清单检查自己的文档。
- 为新技术文档编写人员扩展文档结构。[https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
- 挑选一份适合黑客马拉松的技术文档任务列表。[https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
- 建立技术文档写作中心，指向实用资源。
完善了面向 MediaWiki 摄像师的文档：
- 创建一份快速用户指南，了解如何制作常规抓屏。
- 设计特定于 MediaWiki 的抓屏模板以进行演示和教程。
T214522 [https://phabricator.wikimedia.org/T214522]- 创建“简介 (Introduction to Phabricator)”抓屏。
2.3. 伸展目标
- 请重新检查相应内容并更新 WikiProject Screencast 文档。(https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)
3. 导师
Zulip 将是我的导师的主要沟通方式。我们将使用维基媒体的 IRC 频道和电子邮件与社区进行讨论。 关于具体任务的讨论将在 Phabricator 任务的评论部分进行。
4. 讨论
此项目大致分为两个阶段：
(i) 为维基媒体的技术文档工程师改进现有资源。
(ii) 为有潜力的摄像师创建实用的模板。
(i) 为维基媒体的技术文档工程师改进现有资源。
过去，人们采取了多项举措来改进 MediaWiki 的文档，但取得的成效各不相同。下面列举了一些：
- https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
- https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
- https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
- https://www.mediawiki.org/wiki/User:Waldir/Docs
通过这些努力，我们可以了解到，为技术文档撰写人员提供的一系列更优质的资源将直接影响他们生成的文档。
以下片段摘录自 Outreachy 2018 年实习生 Anna e só（https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/ 每两周发布一次）报告，摘录自：
“MediaWiki 的样式指南并非十全十美，特别是因为它过多地依赖外部引用，而没有重点说明它认为最佳的做法。遗憾的是，这个问题并不仅限于 MediaWiki，其他文档（例如 Translation 最佳实践）中也会有此问题。作家们会缺乏优质可靠的资源来完成作品，这使得他们难以建立目标受众群体和建立适当的写作风格。而用户（尤其是新用户）在理解新概念和流程时可能会遇到问题。”
T197006 [https://phabricator.wikimedia.org/T197006] 还揭示了技术写作文档中有待改进的特定领域。很显然，我们应该从 Documentation/Style_guide 入手。
有了更好的风格指南后，我们计划提供下一组文档，用于指导技术文档撰写人员完成技术文案的不同阶段。这些文档必须适合初学者，同时提供所有必要信息供撰写者参考。
准备阶段可能是最重要的，因为准备阶段是构建文档的基础。为帮助技术文档工程师顺利完成这一阶段，我们制作了参考文档，介绍一些收集相关信息的有效方法以及使用模板构建这些信息的提示。
接下来是写作阶段。我们会为撰写者提供优秀作品的示例，以自动设定高标准。此外，我们还创建了一份核对清单，其中包含每个文档必须遵循的一组基本标准，这有助于撰写者在发布文档之前对其进行检查。
即使有了这些文档，新的技术文档工程师也需要额外的帮助，而我们也需要为他们提供相应帮助。我们为新手技术编程人员优化了指南，并根据难度级别精选了一系列适合黑客马拉松的任务。
最后是一份说明文档管理和维护流程的文档，该文档已经过测试和改进，旨在确定“确定技术文档优先级”。
本阶段结束时，我们将建立一个技术写作指南、资源、示例、建议和模板中心，用于为文档风格指南提供支持。
(ii) 为有潜力的摄像师创建实用的模板。
“要学习任何涉及图形的内容，最难的方法之一就是阅读纯文本。再想象一下，如果您的手册引用了错误的软件版本，会发生什么情况：对于纯文字手册，当应用中的菜单和措辞发生变化时，通常无法重新创建一系列操作，因为我们缺少通常常用的所有提示。
也许最好的学习方式是让专家就在您身边。 抓屏介于静态图片与专家附近。我们通过友好的语音获得一个生动的动画演示，还可以在屏幕和动画上添加文本注释。与专家相比，抓屏有一个优势，就是可以每天每小时随意重放。
我们还可以向抓屏添加翻译后的字幕，以供非母语者查看，或者将音轨替换为其他语言。”
在上面的“抓屏手册”[https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] 的片段中，Ian Ozsvald 介绍了抓屏的重要性。它对于设置 MediaWiki 开发环境、编写扩展程序、使用 Gerrit 等的教程特别有用。
与文档模板类似，使用标准抓屏模板有利于保持一致性，从而改善查看者的体验。此外，它还为潜在的视频制作者提供了入门框架。因此，我们制作了一份快速用户指南，并随后提供了用于制作介绍性视频和教程视频的模板。这些文档包含有关要涵盖的概念深度的指针以及 MediaWiki 的一些抓屏提示。
测试上述模板并为拉伸目标做好准备的最佳方法是使用工具和模板创建抓屏。因此，我们创建了“Introduction to Phabricator”抓屏，其中介绍了使用 Phabricator 的基础知识。此流程还将凸显需要讨论的方面。
最后，我们审核并更新了维基媒体视频制作者的集中参考来源 - WikiProject Screencast。
5. 暂定时间表
社区凝聚期（8 月 1 日 - 9 月 1 日）
- 与我的导师一起详细分析项目。
讨论以下内容：
- 任务的审核频率。
- 分享日程安排并确定每周/每日的工作流程。
- 可以使用的工具和资源。
- 每两周和每日的项目报告。
在 Phabricator 上创建所需的任务和子任务。
创建草稿，弥补在文档开发阶段个人做出的承诺。
第 1 周（9 月 2 日至 8 日）
完善 Documentation/Style_guide：
- 转而重点说明 MediaWiki 上的最佳做法和标准。
- 添加优质案例，提高相关网页的曝光度。
完善面向新技术文档工程师的指南：
- 展开文档结构。
第 2 周（9 月 9 日至 15 日）
确定技术文档的优先级：
- 评估文档工作板；寻找优秀的任务说明和优先级的示例。
- 研究趋势并记下常见困难。
- 使用这些信息和示例记录优先级标准。
第 3 周（9 月 16 日至 22 日）
为技术文档撰写人员创建以下附加文档：
- 一份核对清单，有助于在发布前查看技术文档。
- 针对不同文档类型高效收集内容的方法。
第 4 周（9 月 23 日至 29 日）
在技术文档模板和建议中添加有关使用最常见 MediaWiki 类型编写内容的信息：
- 记录 MediaWiki 上用于编写用户指南、快速入门指南、自述文件、版本说明和方法的最佳实践。
添加有关如何提高技术沟通成熟度的说明。[https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]
第 5 周（9 月 30 日至 10 月 6 日）
完善新协作者的入门文档：
- 更新页面：黑客马拉松的技术文档任务。（待办事项：在项目期间向此页面添加合适的任务）
打造技术文档写作中心
- 创建着陆页，并在其中添加指向实用网页和资源的链接。
- 在新页面和现有页面中添加必要的链接，以便在页面之间更轻松地导航。
第 6 周（10 月 7 日至 13 日）
创建以下关于为 MediaWiki 制作视频的文档：
- 关于“创建常规抓屏”并指向“屏幕录制”项目的快速用户指南。
- 模板适用对象：软件/工具使用演示；新工具开发教程。
为 MediaWiki 创建抓屏创意列表。
第 7 周（10 月 14 日至 20 日）
制作“简介”视频：
- 使用模板（上周创建）来草拟脚本。
- 估算模板的效率，并在必要时加以改进。
- 获取反馈并完成草稿。
第 8 周（10 月 21 日至 27 日）
发布“Introduction to Phabricator”视频：
- 选择并安装软件。
- 设置环境并创建抓屏。
- 记下遇到的问题和解决方案。
第 9 周（10 月 28 日 - 11 月 3 日）
努力完善“屏幕录制”项目文档：
- 研究结构并讨论任何更改需求。
- 查看提到的软件。
- 研究并更新软件清单。
第 10 周（11 月 4 日至 10 日）
继续完善“屏幕录制”项目文档：
- 评估并改进教程和脚本。
- 查看抓屏图库。
第 11 周（11 月 11 日至 17 日）
完成“屏幕录制”项目文档的相关操作：
- 查找较新的视频并将其添加到媒体库。
- 进行必要的结构更改。
第 12 周（11 月 18 日至 24 日）
处理所有待处理的任务。
编写最终报告：
- 参阅每两周/每日的报告，并收集所需信息。
- 规划报告结构并撰写草稿。
- 根据导师的反馈改进并完成初稿。
第 13 周（11 月 25 日至 29 日）
- 提交最终报告和指导评估。
6. 进度跟踪
系统会通过 Zulip 将每日进度更新告知我的导师。维基媒体社区可以通过 Phabricator 或每两周的项目报告跟踪我的进度。
7. 其他承诺
我是全日制大学生，我的秋季学期与 Google 文档季的时间轴重叠。因此，我也承诺参加大学考试。
首次内部考试：8 月 18 日至 24 日
第二次内部考试：9 月 29 日至 10 月 6 日
期末考试：11 月 11 日至 30 日
我还计划在 10 月 12 日至 15 日参加我的第一次公开会议 PyCon India，感谢今年的优越地点。我相信，这是结识新朋友并开展富有洞察力的对话的绝佳机会。
为管理这些承诺，暂定时间表包含相应周内权重较低的任务。我打算在秋季学期完成不超过 20 个核心学分，以便有足够的时间制作文档。（普通学生每个学期平均需要完成 25 个学分）