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