本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- VideoLAN
- 技术文档工程师：
- Edidiong Anny Asikpo
- 项目名称：
- 对 VLC 用户文档进行现代化改造（重写）
- 项目时长：
- 标准时长（3 个月）
Project description
摘要
“用户”文档旨在帮助最终用户使用产品或服务。优秀的用户文档非常重要，因为它为用户提供了学习如何使用软件及其功能、提示和技巧的途径，并能够解决使用软件时遇到的常见问题。它还有助于降低支持成本，并且是产品企业身份之一：良好的用户文档可以证明产品（即开发者团队）是否健康。
如果没有好的用户文档，用户可能不知道如何有效且高效地完成上述操作。在确保产品取得成功方面，用户文档发挥着关键作用，因为良好的沟通是任何业务或产品的核心，并将一直是核心，而出色的文档需要这种沟通，并将其放入易于管理且人人皆可访问的框架中。
到本文撰写之时，VLC 用户文档已获得 4,634,065 次访问，VLC 媒体播放器每月从主网站下载约 2,300 万次，这表明全世界有许多人都在使用 VLC 媒体播放器，并且可能需要阅读其用户文档，以获得有关如何使用媒体播放器的指导。不过，VLC 媒体播放器用户文档目前已过时且不完整（最后更新时间为 2015 年 10 月 28 日），VideoLAN 社区希望利用此项目完善其用户文档，以便让最终用户在使用 VLC 媒体播放器时能够获得顺畅的体验。
当前状态
目前，用户文档可在 Wiki 页面上找到。它已过时、不完整、难以浏览或查找信息，未涵盖有关当前版本媒体播放器的信息，并且只能翻译为德语，这会给不懂英语的用户带来很大的困扰。
为什么我提议的用户文档要对现有文档进行改进？
建议的文档应精心设计，以确保改进并确保最终用户能够获得效率、一致性并使他们安心无忧。该培训内容将包含书面指南及其相关图片，包括有关如何使用 VLC 媒体播放器各项功能的说明和说明，这些内容是最新、易于导航、易于理解并且可翻译的至少五种主要语言。
导师：Jean-Baptiste、Alex、Simon
分析
Jean-Baptiste 和我就当前的用户文档要迁移到的新环境进行了交流，并分享了两个链接。他分享了两个链接，分别显示了用 Sphinx 编写的源文件的 Gitlab 代码库和“Read the Docs”（阅读 Google 文档）上托管的主文档。他说他们希望新文档与该新环境类似。为了更好地了解它们的运作方式，我对这些工具进行了很多研究。
狮身人面像
Sphinx 是一个稳健且成熟的软件文档解决方案。它包含作家期望的多项功能，例如单一源发布、通过“包含”内容重复使用、有条件地包含基于内容类型和标签的内容、多个成熟的 HTML 主题可在移动设备和桌面设备上提供出色的用户体验，跨网页、文档和项目引用 索引和术语库支持以及国际化支持。 它还使用 reStructuredText 作为标记语言，其许多优势源于 reStructuredText 的强大功能和简单性及其翻译文档的能力。
阅读文档
阅读 Google 文档可以为您自动执行文档构建、版本控制和托管，从而简化了软件文档。它永远不会同步；也就是说，无论您何时将代码推送到您喜爱的版本控制系统（无论是 Git、Mercurial、Bazaar 还是 Subversion），“阅读文档”会自动构建您的文档，确保您的代码和文档始终是最新的。它有多个版本；“阅读文档”可以托管和构建您的多个版本的文档，因此拥有 1.0 版文档和 2.0 版文档就像在版本控制系统中有单独的分支或标记一样简单。阅读 Google 文档是免费的开源项目，并为近 10 万个大大小小的开源项目托管了文档，涉及几乎所有人类和计算机语言。
验证
Sphinx 是一款功能极其强大的工具，而“阅读文档”基于其构建，为 Sphinx 文档提供托管服务，让您的文档在各个版本上保持最新。二者共同构成了一套出色的工具，可供开发者和技术文档工程师创建最适合最终用户的用户文档。
Sphinx 支持将文档翻译成多种语言。它支持版本控制，将用于管理文档。与目前的维基百科（任何人都可以编辑，但无法添加正确的信息）不同的是，这个版本控制系统会确保所有更改在合并到主代码库之前都必须先经过审核。版本控制还可以提高文档对项目的开源贡献，因为人们可以创建问题、打开拉取请求等。Sphinx 和阅读 Google 文档被众多其他优秀社区（如 ASP.NET、内核、Julia、Jupyter、PHPMyAdmin、Write theDocs 等）使用，它是用于新建 VLC 用户文档的绝佳工具。
我不仅仅了解了这些工具，还创建了一个基本示例。我的 Gitlab 代码库为 https://gitlab.com/Didicodes/demo-vlc-user-documentation 的链接，而 readthedocs 上的托管版本位于此处：[https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/)。
提议的文档结构
我创建了一个 VLC 用户文档的结构，该文档位于以下位置：https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing。 这种新结构必须先获得导师的批准，然后才能开始实施。这意味着结构在通过导师审核后可能会发生变化。
项目目标
- 重构文档。
- 更新文档以适应现代版本的 VLC。
- 使用 Sphinx 和 ReadtheDocs 将用户文档迁移到 Gitlab。
- 移除过时的图片和信息。
- 重写用户文档，使其更易于理解。
- 使用 Sphinx Internationalization 进行设置，以便进行翻译。
- 将文档打造为社区驱动型文档，以便用户报告或解决在阅读文档时遇到的任何问题。
为何推出此项目？
我一直坚信，只要有能力通过写作启发他人，就能够充分发挥代码、解决问题和构建软件的潜力，我就坚信这一点。就我个人而言，VideoLAN 社区致力于开发适用于多媒体的免费软件解决方案，让我一直着迷。小时候我小时候，VLC 媒体播放器一直是我在听音乐或看电影时使用的软件，因为它声音很大，并且包含很多功能。能够与社区合作，让我的童年变得精彩纷呈，我很荣幸。
为什么我是此项目的合适人选
我认为自己是该项目的合适人选，原因如下：
- 我拥有完善组织文档的经验，可以使用任何版本控制系统，因此在 Gitab 上执行命令不会成为问题。此外，推动我开展一些能够为人们创造价值的项目是我的动力所在。
- 我相信，如果您希望某人以尽可能高效的方式完成某件事，您可以记录下来。通过记录您的流程，您可以确保所有相关人员都能提高效率、一致性并让他们安心无忧。
- 我了解 VLC 用户的需求，因为我也是其中之一。这样，您在编写文档时，全球各地的所有其他用户都可以一目了然地看懂。