VideoLAN 项目

本页面包含 Google 文档季接受的技术写作项目的详细信息。

项目摘要

开源组织：
VideoLAN
技术文档工程师：
Edidiong Anny Asikpo
项目名称：
改进（重写）VLC 用户文档
项目时长：
标准时长（3 个月）

Project description

ABSTRACT

用户文档旨在协助最终用户使用产品或服务。优质的用户文档非常重要，因为它为用户提供了了解如何使用软件、软件的功能、提示和技巧，以及解决使用软件时遇到的常见问题的途径。同时，它还有助于降低支持成本，并且是产品的企业标识：良好的用户文档意味着产品、开发者团队运行良好。

如果没有良好的用户文档，用户可能不知道如何高效地执行上述操作。用户文档在确保产品取得成功方面发挥着至关重要的作用，因为良好的沟通一直是任何业务或产品的核心，而出色的文档能够满足沟通需求，并将其纳入一个人人都能访问的可管理的框架中，从而取得成功。

在撰写本文时，VLC 用户文档的访问量已达到 4,634,065 次，VLC 媒体播放器从主网站下载的次数每月约为 2,300 万次，这表明世界各地有许多人使用 VLC 媒体播放器，并且可能希望阅读其用户文档，以获取有关如何使用该媒体播放器的指导。不过，VLC 媒体播放器用户文档目前已过时且不完整（上次修改时间为 2015 年 10 月 28 日），VideoLAN 社区希望通过此项目改进其用户文档，让最终用户在使用 VLC 媒体播放器时获得流畅的体验。

当前状态

目前，用户文档可在维基页面上找到。该文档已过时、不完整、难以浏览或查找信息，不涵盖有关媒体播放器当前版本的信息，并且只能翻译成德语，这对不懂英语的用户来说是一个重大障碍。

WHY IS MY PROPOSED USER DOCUMENTATION AN IMPROVEMENT OVER THE CURRENT ONE?

我们将以合理的结构编写建议的用户文档，以提高效率、确保一致性并让最终用户安心。该指南将包含书面指南及其相关图片，并包含有关如何使用 VLC 媒体播放器的各项功能的说明和解释，且该指南应处于最新状态、易于浏览、易于理解，并至少提供 5 种主要语言的译文。

导师：Jean-Baptiste、Alex、Simon

分析

Jean-Baptiste 和我讨论了当前用户文档将迁移到的新环境，以便进行改进。他分享了两个链接，分别显示了使用 Sphinx 编写的源文件的 Gitlab 代码库，以及托管在 Read the Docs 上的主要文档。他表示，他们希望新文档与之类似。我对这些工具进行了大量研究，以便更好地了解其运作方式。

狮身人面像

Sphinx 是一款强大且成熟的软件文档解决方案。它包含编写者期望的多项功能，例如单源发布、通过包含功能重复使用内容、基于内容类型和标记的条件包含、多个成熟的 HTML 主题（可在移动设备和桌面设备上提供出色的用户体验）、跨页面、文档和项目引用、索引和术语表支持以及国际化支持。它还使用 reStructuredText 作为标记语言，其许多优势都源于 reStructuredText 的强大和简单，以及其能够翻译文档。

阅读文档

Read the Docs 可自动为您构建、版本控制和托管文档，从而简化软件文档的管理。它永远不会出现同步问题；也就是说，每当您将代码推送到您喜爱的版本控制系统（无论是 Git、Mercurial、Bazaar 还是 Subversion）时，Read the Docs 都会自动构建文档，以便您的代码和文档始终保持最新状态。它有多个版本；“阅读 Google 文档”可以托管和构建您的文档的多个版本，因此，创建 1.0 版本的文档和 2.0 版本的文档就像在版本控制系统中使用单独的分支或标记一样简单。Read the Docs 是一个免费的开源平台，托管了近 10 万个大型和小型开源项目的文档，这些文档几乎涵盖了所有人类和计算机语言。

VERDICT

Sphinx 是一款非常强大的工具，Read the Docs 基于 Sphinx 构建，可为 Sphinx 文档提供托管服务，确保您的文档在各个版本中保持最新状态。这些工具相辅相成，开发者和技术文档撰写者可以使用它们来创建最适合最终用户的用户文档。

Sphinx 支持将文档翻译成多种语言。它支持用于管理文档的版本控制。与当前的维基不同，任何人都可以编辑当前维基，但不能添加正确的信息。而此版本控制系统会确保所有更改都先经过审核，然后再合并到主代码库。版本控制还可以让文档为项目增加开源贡献，因为用户可以创建问题、打开拉取请求等。Sphinx 和 Read the Docs 被许多其他优秀的社区使用，例如 ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、Write the Docs 等，是用于新 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 媒体播放器从小到大，一直都是我听音乐或看电影时使用的软件，因为它声音很大，并且包含很多功能。能与为我度过美好童年的社区合作，我深感荣幸。

为什么我适合此项目

我相信自己适合开展这个项目，因为：

  • 我过去曾负责改进组织的文档，并且可以使用任何版本控制系统，因此在 GitHub 上执行命令不会有任何问题。此外，我还会参与一些能够为用户创造价值的项目。
  • 我认为，如果您希望某人以最有效的方式执行某项操作，就需要记录相关信息。通过记录流程，您可以确保效率、一致性，并让所有相关人员都能高枕无忧。
  • 我了解 VLC 用户的需求，因为我是他们中的一员。这样，您就可以撰写出让全球所有其他用户一目了然的文档。