本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Matplotlib
- 技术文档工程师：
- jeromev
- 项目名称：
- 开发 Matplotlib 入口路径
- 项目时长：
- 标准时长（3 个月）
Project description
简介
Matplotlib 为今年的 Google 文档季推荐的项目涉及创建有助于向新用户介绍 Matplotlib 的内容。对于《开发 Matplotlib 条目路径》，我提出了一种替代方法，用于代替当前文档。我是该行业的新技术文档工程师；不过，我的背景是教育和教育相关领域。技术文档和教育内容有许多相似之处，都致力于制作能够体现同理心的内容，让用户能够利用所提供的资源完成任务。
在这种情况下，Matplotlib 文档可以改进，以便更好地体谅新用户。目前，大部分素材都包含随机数据和未标记的视觉内容。这些库非常适合快速显示 Matplotlib 的视觉效果和功能。不过，对于刚开始接触 Matplotlib 的用户，将数据转换为可视化内容的过程非常具有挑战性。
说明法中的上下文可解决此问题。通过以实际示例为视角编写过程，我们展示了对用户工作环境的理解。这有助于在达成目标或完成任务方面改善文档与用户之间的关系。
用户具有一致的派生用途。例如，鞋业公司的数据科学家必须向一个团队展示客户数据，以说明一段时间内的购物趋势。在这种情况下，用户必须学会浏览 Matplotlib，并利用库中的工具完成手头的任务。
通过提供额外的背景信息来辅助文档，新用户或许更能理解相关主题。用户的派生用途与文档相一致。我希望实现首席开发者 Tom Caswell 在 2017 年接受采访时提出的愿景：“让能够实际编写文档且对用户有同理心的人员，撰写一本 200 页的《Matplotlib 简介》图书，并将其作为文档的主要入口。”
说明文写作替代方法
当前文档演示了 Matplotlib 的功能，即用户可以使用该库执行的操作。例如，教程通常遵循不涉及对底层方法进行说明的模式。
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
在编程文档和支持方面，通常建议用户自行运行代码，以了解会发生什么情况。虽然编程思维有助于用户更好地理解该主题，但转换的学习曲线缺少支持内容。由于文档有限，这可能会带来巨大的挑战。
提供额外的图表、图片或其他视觉内容有助于创造新的学习机会。以下结构也可以用作新内容的模板。此外，添加非文字图片或图形时，可以利用宣传信息和教程标记等功能。有时，图片难以浏览，因为没有指明代码如何或在何处转换为执行的输出。我认为，其中缺少一个鲜明的视觉元素，这应该有助于加深对各个主题的理解。
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
这种使用说明性写作进行文档的替代方法具有巨大的潜力。用户可以看到各种转换概念，从而更好地了解将数据转换为可视化图表的底层策略。这些知识可以帮助用户根据真实的使用场景中提供的示例进行创新并充分利用这些功能。
随着 Matplotlib 的普及，其易用性和易上手性始终如一，这证明了该库的声誉。这些特性有助于演示模式和通用策略，它们不仅存在于代码之中，也体现在文档中。Matplotlib 的使用越来越广泛，资源也越来越丰富，这表明 Matplotlib 对用户来说是简单标准的编程工具，同样，它对技术文档来说也是如此。
当用户遇到问题时，通常可以使用搜索来解决问题。让用户在文档中构建自己的课程，而不是依赖搜索作为主要导航方法，这样做可能更有成效。从这个意义上讲，用户搜索问题的解决方案，然后在遇到其他问题或想要了解更多信息时，会使用随处嵌入的详尽链接。
这需要在组织系统中采用自下而上的架构。对于 Matplotlib 中的每个主题，丰富的主题关联和信息主题链接网络有助于构建强大的网络。在整个网络中，用户在浏览到所需主题并探索与该主题相关的更多信息时，更有可能继续使用文档。
障碍
像这样全面而详细的项目总会遇到一些挑战。作为业内新手技术文档撰写者，我使用 Sphinx 和 ReST 编写文档的经验有限。我对 Matplotlib 和 Git 也还处于新手阶段。要想掌握这四种系统，并能够熟练地将它们用于协作和研究，需要花费一些时间。我需要在社区互动阶段和之前留出时间，为入门级路径奠定必要的基础。在此期间，如果我对概念和基础知识有任何疑问，则需要与社区联系以获取更多支持。
协调跨时区和跨在线平台的协作工作也需要做出一些调整。整个行业的人们都使用各种各样的沟通渠道，因此我需要确保自己能够通过所有媒介与人沟通，并且能够随时与人联系。在整个过程中，我会清楚透明地确定各种预期的优先级。虽然我刚刚开始在该行业接手这类工作，但我会努力承担起自己的责任，并乐于接受反馈和批评。我认为，无论是在哪个领域，这些品质都很重要。
此外，我认为增加易用性测试是文档中的一个部分，对 Matplotlib 的入门路径有益。针对内容的可用性开展调查旨在提供用户画像（即角色）。用户的使用体验、所属行业和问题排查记录等信息非常有价值。这些部分有助于形成该过程背后的语言。当内容符合读者的水平时，内容就不仅仅是提供指导，而是更具成熟性。
最大的难题通常在于建立持续进行可用性测试的做法。在内容开发过程中，仅进行一次测试（如果有的话）的情况非常常见。定期进行易用性测试有助于推动内容的叙事性。我希望能与 Matplotlib 社区一起制定时间表或定期进行易用性测试。
总结
我在空闲时有使用 Python 和 Matplotlib 的经验。过去几个月来，我通过当前的文档和自己的好奇心自学了很多知识。那段时间，我还看了一些视频，并得到了一些导师的指导。我还有很多东西要学，并且在构建自己感兴趣的编程课程时，还有很大的提升空间。
在了解了 Matplotlib 和社区为 GSoD 提供的想法后，我认为这将是一次绝佳的成长经历，可以提升我作为技术文档撰写者的技能，并有机会向幕后人员学习更多知识。我认为这个 Matplotlib 项目既有意义，又是我热衷的理念。
作为一名技术文档撰写者，我负责全面改进使用指南，目标是帮助用户完成他们想要完成的任务，而不会被可用功能所淹没。我认为，最优秀的文档会不断发展壮大，并根据用户的需求进行调整，让任何用户都能找到自己的解决方案。