本页详细介绍了 Google 文档季收录的技术文案项目。
项目摘要
- 开源组织：
- VLC
- 技术文档工程师：
- Abhishek Pratap Singh
- 项目名称：
- 继续对 VLC 用户文档进行现代化改造
- 项目时长：
- 标准时长（3 个月）
Project description
文档的当前状态
VLC 用户文档正在进行现代化改进和更新。我们正在从基于 Wiki 的旧版文档 [1] 过渡到托管在 ReadTheDocs 上的 Sphinx 构建的新型用户文档 [2]。
TARGET AUDIENCE
目标受众群体既包括希望探索 VLC 媒体播放器超出普通媒体播放器功能的好奇用户，也包括在某种程度上可作为简单参考指南帮助开发者的用户。因此，我打算既添加基于 GUI 的指令（以及相关的图片）和基于 CLI 的方法（以及代码段），以便最终用户可以自由选择。
我认为，文档中的用词（尤其是 GUI 部分）应尽量简单，以便仅有少量计算机操作经验的用户也能理解并实现该指南。另一方面，说明不应过于冗长（尤其是 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 内容
交付成果 2 [第 3-4 周]：更新使用 VLC 作为 Web 插件 [6]，同时在 Firefox 77、Chrome 83 和 Edge 83 中进行测试。
- 制作包含视频的网页
- 嵌入代码属性
- JavaScript API 说明
交付成果 3 [第 5 周]：测试命令行界面 [7] 命令并相应地进行更新。
- 视频流
- 模块选择
- 商品专用选项
- 过滤条件
第 6 周：上述三项交付项的缓冲周。
交付 4 [第 7-8 周]：准备翻译。 除了更新之外，我还会准备将其翻译成其他语言。这一点非常重要，因为翻译之后，没有英语背景的用户也能阅读相关文档（顺便说一句，VLC 将朝着实现“世界称霸”目标更近一步 [8]）。
如提案的“工具”部分所述，VLC 目前使用 Babel 生成 .po 文件以供翻译。我将记录用户/志愿者执行以下操作的流程：
- 在本地下载并构建基础文档。
- 使用 Babel 生成所需的文件。
- 输入字符串的翻译。
- 使用 Sphinx 构建翻译后的文档。
- 提交更改。
交付成果 5 [第 9-10 周]：准备模块文档。 正如与导师讨论过的，我计划分两个部分来准备模块文档。
第 1 部分：通过脚本创建靠近模块的文件，该脚本会从代码库中查找有效选项，并从相应 Wiki 页面中提取其一行用途（和默认值）。这将作为基本草稿。
第 2 部分：构建特定于平台的结构，用于关联特定平台（Windows，如果时间允许，还包括 Fedora）的所有模块、插件和选项。
在模块附近创建文件可确保文档靠近源代码。采用自下而上的方法，将通过组合第 I 部分创建的文件并使用第 II 部分创建的结构作为参考来构建主要模块文档。
通过自动化操作创建的文件需要经过审核，但首要任务是创建一个功能框架。完成此操作后，根据时间，我会查看文件以验证相关选项。我们正在优先开发该框架，因为该框架一经发布，开发者和维护者还可以通过添加相关用例来开始贡献。
额外提交内容 [第 11 周]：为 4.0 版发布做好准备。 如果项目按计划进行，我想提议提供额外的交付成果。正如与导师讨论的那样，为 4.0 版本做好准备意味着拥有稳定且几乎完整的版本 3.0 文档。
因此，我会查看已完成的以下部分的文档，以验证和更新所述的方法：
- 基本使用：媒体、播放、音频、视频、字幕、热键、录制、设置、提示和技巧。
- 高级使用：播放器、界面、转码、流式传输、异常情况。
- 插件：扩展程序、皮肤。
第 12 周：上述三项交付成果的缓冲周及最终报告。
WHY AM I THE RIGHT PERSON FOR THIS PROJECT?
作为一名技术爱好者，我有使用/测试软件的经验，有时还会尝试理解其代码库。事实上，在尝试了解开源组织的代码库时，我才第一次真正意识到文档的重要性。此外，作为音乐爱好者，我对 VLC 的调整有丰富的经验 :)
除此之外，我一直是一名研究员和作家。除非我写下某些内容，否则我永远无法真正理解它们，而正是这种习惯让我成为了高效的记事者和文档编写者。
正是这两种习惯的结合，让我非常适合撰写技术文档。我可以应对技术方面的问题，并以用户能够理解的方式记录我的发现/流程。
Links: [1] [1] https://wiki.videolan.org/Documentation:org/Documentation:User_7