本页详细介绍了 Google 文档季收录的技术文案项目。
项目摘要
- 开源组织：
- 维基媒体基金会
- 技术文档工程师：
- Pavithra Eswaramoorthy
- 项目名称：
- 改进了 Wikimedia 技术文档人员和摄影师的文档
- 项目时长：
- 标准时长（3 个月）
Project description
1. 关于我
我在几个月前开始接触开源软件，对它的无限范围几乎立即感到不知所措。在努力探索数以亿计的项目时，我了解到了 Google 编程之夏和 Outreachy 等开放源代码计划。Google 文档季似乎很有趣，而 Wikimedia Foundation 的项目想法也激发了我的好奇心，于是我开始进一步探索。
到目前为止，我的历程既令人兴奋又令人困惑，充满了“等等，什么？”“啊，我明白了！”和“我应该对此发表评论吗？”。Wikimedia 社区在每一步都给予了支持。从编辑网页到创建扩展程序，我每天都在学习新知识。
正如预期的那样，申请流程成为了我进入开源社区的门户。 此提案的灵感来自我自己作为新手的经历。
2. 项目
2.1. 轮廓
此项目旨在为 Wikimedia 的技术文档撰写者和潜在的视频制作者改进文档。 一套成熟的技术文档准则有助于改进整体文档，而有关创建屏幕录制的参考文档则有助于有效演示软件功能。我们可以扩展这些领域现有文档，以便更好地为新手和资深贡献者提供支持。我们将采用增量方法来构建这个实用资源网络。
2.2. 交付成果
T197006 [https://phabricator.wikimedia.org/T197006] - 改进了 Wikimedia 文档人员的文档：
- 在文档/样式指南中添加了提示和示例。[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]- 创建“ Phabricator 简介”抓屏。
2.3. 伸展目标
- 重新检查内容并更新 WikiProject Screencast 文档。(https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)
3. 导师
Zulip 将成为我与导师沟通的主要方式。Wikimedia 的 IRC 频道和电子邮件将用于与社区讨论。 有关特定任务的讨论将在 Phabricator 任务的评论部分进行。
4. 讨论
此项目大致分为两个阶段：
(i) 完善维基媒体技术人员的现有资源。
(ii) 为潜在摄像师创建实用的模板。
(i) 改进 Wikimedia 技术文档作者的现有资源。
过去，我们曾推出过几项旨在改进 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 的基础知识。此过程还会突出显示需要讨论的方面。
最后，我们审核并更新了 Wikimedia 摄影师的核心参考资料 - WikiProject Screencast。
5. 暂定时间表
社区互动期（8 月 1 日至 9 月 1 日）
- 与导师一起详细分析项目。
讨论以下内容：
- 任务的审核频率。
- 分享时间表并确定每周/每天的工作流。
- 可使用的工具和资源。
- 每两周和每天生成一次的项目报告。
在 Phabricator 上创建所需的任务和子任务。
创建草稿，以弥补文档开发阶段的个人承诺。
第 1 周（9 月 2 日至 8 日）
改进文档/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 日）
观看“Phabricator 简介”视频：
- 使用模板（于上周创建）起草脚本。
- 估算模板的效率，并根据需要进行改进。
- 获取反馈并最终确定草稿。
第 8 周（10 月 21 日至 27 日）
发布“Phabricator 简介”视频：
- 选择并安装软件。
- 设置环境并创建抓屏。
- 记下遇到的问题和解决方案。
第 9 周（10 月 28 日至 11 月 3 日）
努力改进屏幕录制项目文档：
- 检查结构，并讨论是否需要进行任何更改。
- 查看提及的软件。
- 研究并更新软件列表。
第 10 周（11 月 4 日至 10 日）
继续改进屏幕录制项目文档：
- 评估并改进本教程和脚本。
- 查看屏幕演示库。
第 11 周（11 月 11 日至 17 日）
完成屏幕录制项目文档的工作：
- 查找并将较新的视频添加到图库。
- 进行必要的结构性更改。
第 12 周（11 月 18 日至 24 日）
处理所有待处理的任务。
撰写最终报告：
- 查看每两周/每天生成的报告，并收集所需信息。
- 规划报告结构并撰写草稿。
- 根据导师的反馈改进草稿并最终确定。
第 13 周（11 月 25 日至 29 日）
- 提交最终报告和导师评估。
6. 进度跟踪
我会通过 Zulip 向导师通报每日进度更新。Wikimedia 社区可以通过 Phabricator 或每两周一次的项目报告跟踪我的进度。
7. 其他承诺
我是全日制大学生，我的秋季学期与 Google 文档季的时间表重叠。因此，我的承诺包括大学考试。
第一次内部考试：8 月 18 日至 24 日
第二次内部考试：9 月 29 日至 10 月 6 日
期末考试：11 月 11 日至 11 月 30 日
我还计划在 10 月 12 日至 15 日参加我的首场公开会议 PyCon India，因为今年的会议地点比较有利。我相信这是结识新朋友、进行富有见地的对话的大好机会。
为了管理这些承诺，暂定时间表会在相应的周内包含权重较低的任务。我打算在秋季学期完成的核心学分不超过 20 个，以便有足够的时间进行文档开发。（普通学生平均每学期完成 25 个学分）