本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- VLC
- 技术文档工程师：
- Avii
- 项目名称：
- 为一个移动端口 (Android) 创建 VLC 用户文档
- 项目时长：
- 标准时长（3 个月）
Project description
ABSTRACT
用户文档可用作为最终用户提供帮助的静态支持系统。它提供有关产品或服务的技术和非技术信息。它可以帮助用户了解如何使用软件或服务。并非所有用户都希望与支持团队联系或等待电子邮件回复，有些用户只需要一些指导、提示或技巧。用户文档就是为此而生。这还能降低支持成本，并体现产品的健康状况和开发者团队的专业水平。
仅从 Google Play 商店下载 Android 版 VLC 的次数就已超过 1 亿次。VLC 为其移动端版本提供了许多功能，从音视频播放到网络流式传输。人们常常想使用这些出色的功能，但却无法实现。为此，他们需要花费大量时间和耐心来搜索博客或一些随机视频，但获得的信息仍然无法保证真实性。目前，VLC 在维基页面上托管 VLC for Android 用户文档，并且对这些功能的说明较少或不提供说明。除此之外，Wiki 页面的最后更新时间为 2019 年 3 月。当前项目将提供新的用户文档，采用现代设计，并使 Android 端口更易于使用。
当前形势
Wiki 页面完全已过时，而且包含的 VLC 最新版本信息非常少。此外，这些页面也不易于浏览。没有可见的选项可用于以非英语阅读文档。完全不包含功能说明。
分析
-> 目前，当前文档已过时，需要采用新的方式并使用其他平台和工具进行编写。
-> 大多数 Android 用户仅具备很少的技术知识或一无所知。但有些用户需要有关功能的更多技术信息。为上述每种用途分别编写和维护两个文档不是一个好主意。即使在同一文档中，根据技术性和非技术性对功能进行划分也会造成额外的混淆。再次强调一下，大多数用户都习惯于所看到的界面或所使用的功能，因此并非所有人都能轻松判断某项内容是技术性还是非技术性内容。因此，我们希望为他们简化操作。
-> 大多数用户会尝试通过智能手机获取信息，其余用户则会通过桌面设备或其他设备获取信息。因此，文档应能够轻松适应各种屏幕尺寸。并且不得造成导航方面的混淆。
-> 桌面版的部分功能在 Android 版本中不可用，即使可用，在两个版本中的运作方式也不尽相同。这是因为桌面应用的开发时间远长，已经达到一定的饱和状态，相比之下，移动端口相对较新，仍处于开发阶段。除此之外，尽管如今的移动设备变得如此强大，但我们能够纳入的功能类型存在明显的限制，这主要是因为最终用户的需求。开发没人使用的功能是一种资源浪费。因此，不建议根据功能来翻译这两种文档。
根据上述分析，我提出以下建议。 1. 目前，桌面版用户文档使用的是 Sphinx 文档生成器和 Read the Docs 主题。为 Android 端口使用相同的 API 可以通过以下方式帮助我们： -> 轻松合并这两个文档。 -> 它已针对所有屏幕尺寸进行了优化。 -> 通过桌面版文档导航到 Android 用户文档时获得顺畅体验
- 根据章节、部分和子部分在应用中的相对位置进行分隔。例如，“后台/画中画模式”位于“更多”->“设置”->“视频”中，因此章节结构将如下所示：
- 展开
- |__Settings
- | |__媒体库
- | |__视频 -->后台/画中画模式
- ： -> 这种方法可以提高易用性，因为用户可以通过将其与应用中的相对位置进行比较，轻松找到需要帮助的部分。对于每个功能，我们都可以进一步将其分为技术部分和非技术部分。我们应先撰写非技术性简单说明，然后在其下方进一步突出显示或标记同一功能的技术部分（如果有）。这可能会重复一些要求，但可以确保非技术多数人的顺畅体验。这也有助于提高可维护性，为日后带来帮助。由于应用将达到饱和状态，因此相关界面不太可能会发生太大变化，因此日后如果添加/移除新功能，我们只需重构该部分即可。如果整个界面发生变化，我们可以重新排列部分/章节或重构整个文档，无论是哪种情况，我们都需要修改整个文档，因为屏幕截图必须替换为与当前界面相符的屏幕截图。如需查看操作演示，请访问以下链接：https://avinal.gitlab.io/vlc-android-docs/
该文档的每个部分都应包含带标签的屏幕截图、功能说明、偏技术部分（如果有），以及功能提示和技巧。
-> 在桌面设备上独立开发此用户文档有助于我们只需几步即可合并这两份文档，而不会影响当前文档，也不会在开发过程中受到其影响。我建议在完成开发后，将本文档的全部内容放入桌面版文档的 Android 部分，然后为 VLC for Android 文档创建永久链接。
-> 其他改进可能包括重新设计桌面版用户文档的初始页，让用户直接选择他们喜欢的操作系统，然后重定向到所选操作系统的文档。由于 Windows、MacOS 和 Linux 版 VLC 用户文档已经设计得很好，我们可能会提供 Windows/MacOS/Linux 或 Android 或 iOS 选项。这样一来，用户文档就会分门别类，但又保持统一，只需一个链接即可用于所有端口。
WHY IS MY PROPOSED USER DOCUMENTATION BETTER? 本提议的用户文档是基于常见模式，最终用户可通过该模式获得帮助。该文档结合了所有必需的功能（例如简单性、清晰度、外观和风格、技术知识），以最大限度地提高易用性和最终用户体验。这样一来，您无需再为每个端口维护单独的用户文档，因此也更易于维护。
WHY AM I RIGHT PERSON FOR THIS PROJECT? -> 我已经编写代码 2 年了，经常需要查看特定库或某些软件的 API 文档，甚至编写自己的代码文档。所以我确切地知道人们想在文档中看到什么内容，他们遇到了什么问题，以及如何寻求帮助。我将能够运用同样的经验来编写一致且易于阅读的文档。
-> 我一直在 Quora、Stack Overflow 和其他各种平台上积极撰写技术内容。我知道如何以简单易懂的方式说明事项。
-> VLC for Android 是一款功能强大且广为人知的工具，但其大多数功能都鲜为人知，或者没有任何帮助。我已经在桌面平台和移动平台上使用 VLC 多年，因此了解用户可能会遇到哪些问题。我会综合运用自己的所有知识和经验，确保提供优质的文档。