本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- VLC
- 技术文档工程师：
- Abhishek Pratap Singh
- 项目名称：
- 继续进行 VLC 用户文档的现代化改造
- 项目时长：
- 标准时长（3 个月）
Project description
文档的当前状态
我们正在对 VLC 用户文档进行现代化改造和更新。我们正在进行转换，以便从基于 Wiki 的旧文档 [1] 迁移到 ReadTheDocs 上托管的 sphinx 构建的现代用户文档 [2]。
目标受众群体
目标受众群体既是对 VLC 媒体播放器的好奇心，也希望了解 VLC 媒体播放器比普通媒体播放器更强大的功能。在某种程度上，该播放器可作为一份简单的参考指南来帮助开发者。因此，我计划同时添加基于 GUI 的说明（以及相关图片）和基于 CLI 的方法（和代码段），以便最终用户可以自由选择。
我认为文档（尤其是统一发票部分）的措辞应该足够精简，以便名义接触操作计算机的人能够理解和实施该指南。另一方面，不应因为过长或带有解释（尤其是 CLI 部分）而使程序员失去兴趣。
要实现恰到好处的平衡，请在网页开头提及相关前提条件，或保留一些知识渊博的用户可以跳过的可选部分。
构建翻译的目标受众群体是精通英语和目标语言的 VLC 开发者/用户。
工具
新文档由 Sphinx 构建并托管在 ReadTheDocs 上，并且版本控制系统在 GitLab 中实现。我之前有过使用 Git 和 GitHub 的经验，虽然有些不同的功能需要一些时间学习，但我掌握了 GitLab。
至于 Sphinx，我曾在一位开源爱好者评论过许多组织正在使用它来构建文档（以 Blender 为例，它使用 Sphinx 编写用户手册 [3] 和 API 文档 [4]），
我有点熟悉 ReadTheDocs，它是一个用于版本控制和托管技术文档的好工具。因此，我能够顺利地构建 VLC 文档，并且熟悉所用的格式重新结构化文本。
对于翻译，VLC 会使用 Babel 生成 .po 文件，以便实现 i18n 和 l10n。目前，我熟悉 Babel 工作流程以及如何使用 Sphinx 构建 .mo 文件。
我打算利用绑定期来进一步熟悉上述工具的复杂性。
交付物和每周时间表
作为 2019 年项目的一部分，我们已介绍了安装、界面、音频、视频、播放等部分（大多数基本功能）。因此，对于 2020 项目，我想更新并改进“用户”文档的高级用法部分。
可交付 1 [第 1-2 周]：更新转码文档，如第 7[5] 中所述。
- 转码
- 对多个视频进行转码
- 请添加徽标
- 将视频合并在一起
- 从文件中提取音频和提取音频
- 翻转 DVD
DELIVERABLE 2 [第 3-4 周]：使用 VLC 作为网络插件进行更新 [6]，同时在 Firefox 77、Chrome 83 和 Edge 83 中进行测试。
- 制作包含视频的网页
- Embed 标记属性
- JavaScript API 说明
DELIVERABLE 3 [第 5 周]：测试命令行界面 [7] 命令并相应地进行更新。
- 数据流
- 模块选择
- 特定于商品的选项
- 过滤条件
第 6 周：为上述三项交付成果开展缓冲周。
交付 4 [第 7-8 周]：准备翻译。 除了更新，我还会准备将内容翻译成其他语言。这一点非常重要，因为翻译完成后，没有英语背景的用户将能够阅读相关文档（顺便说一句，VLC 是实现“世界统治”的目标更进一步 [8]）。
如该提案的“工具”部分所述，VLC 目前使用 Babel 生成 .po 文件进行翻译。我会将用户/志愿者的流程记录下来：
- 在本地下载并构建基础文档。
- 使用 Babel 生成所需的文件。
- 输入字符串的翻译。
- 使用 Sphinx 构建翻译后的文档。
- 提交更改。
DELIVERABLE 5 [第 9-10 周]：为编写模块文档做准备。 正如与导师讨论的那样，我计划分两部分准备模块文档。
第 - I 部分：通过从代码库中查找有效选项并从相应的 Wiki 页面提取其单行用法（和默认值）的脚本，在模块附近创建文件。可以作为一个基本草稿。
第 - II 部分：构建平台专用结构，将特定平台的所有模块+插件+选项链接起来（Windows，如果时间允许，还适用于 Fedora）。
在模块附近创建文件可以确保文档接近源代码。我们采用自下而上的方法构建主要的“模块文档”，将在第 I 部分中制作的文件与第 II 部分中制作的结构作为参考进行构建。
通过自动化创建的文件需要接受审核，但首要任务是构建功能框架。完成设置后，根据时间，我会查看相关文件以验证这些选项。该框架一经推出，开发者和维护者也可以开始通过添加相关用例做出贡献。
奖励分发 [第 11 周]：为 4.0 发布做准备。 为确保项目按计划进度，我想提议一个可交付成果的奖金。正如与导师讨论的那样，为 4.0 版本做准备意味着拥有版本 3.0 的稳定且几乎完整的文档。
因此，我会查看以下各部分已完成的文档，以验证和更新所述方法：
- 基本用法：媒体、播放、音频、视频、字幕、热键、录制、设置、提示和技巧。
- 高级用法：播放器、接口、转码、流式传输、异常情况。
- 插件：扩展程序、皮肤。
第 12 周：缓冲周 - 为上述三项交付成果 + 最终报告。
为什么说我是这个项目的合适人选？
作为一名技术爱好者，我有使用/测试软件的经验，有时还会尝试从他们的代码库中理解相关信息。事实上，我第一次真正认识到文档的重要性，尝试了解开源组织的代码库。此外，作为一名音乐爱好者，我有很多使用 VLC 调整工作的经验 :)
除此之外，我一生都是一名研究人员和作家。除非我把内容写下来，否则我从来不会真正理解这些内容，但这一习惯使我成为了一名高效的笔记者和记录者。
这两个习惯的交集使得我非常适合编写技术文档。我可以找到技术方面的问题，并以方便用户理解的方式记录发现/流程。
链接： [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/zh-CN/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/docs/wiki/docs/wiki/docs/wiki/docs/wiki/docs/wiki/docs/wiki/intl/zh_cn/docs/wiki/docs/wiki/wiki/wiki/wiki/%E6%36%E6%A0%81%E7%A0%81%E7%A7%81%E7%A8%E7%A0%81