本页面包含有关 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 中的每个主题，丰富的主题相似性链接和信息主题链接有助于建立强大的网络。在整个网络中，当用户导航到自己的主题并探索与该主题相关的越来越多信息时，会更愿意继续使用相关文档。
障碍
像这样全面和细致的项目，总是会遇到挑战。作为业内新手的技术文档工程师，我使用 Sphinx 和 ReST 编写文档的经验有限。说到 Matplotlib 和 Git，我还是初学者。解决这四个系统并适应使用它们进行协作和研究需要一些时间。我需要在社区凝聚阶段及更早的阶段分配时间，以便为入门级学习路径打下必要的基础。在此期间，如果我遇到概念和基础知识方面的问题，则需要与社区联系以获取更多支持。
如果跨时区和在线平台协调协作，也会发生一些调整。在整个行业中，人们使用的沟通途径多种多样，因此，我的问题在于确保我在各种媒介中都易于理解并且平易近人。在整个过程中，我将坦诚透明地告知大家不同期望的优先顺序。虽然我才刚开始从事诸如此类的工作，但我致力于让自己有责任感，并乐于接受反馈和批评。我觉得无论在哪个领域，这些品质都很有价值。
此外，我认为增加易用性测试是文档的一部分，我认为 Matplotlib 的入门路径是有益的。针对内容的可用性开展调查，目的在于提供用户个人资料（即角色）。用户的体验、所在行业和问题排查历史记录等信息都很有价值。这些内容有助于构成流程背后的语言。如果所写的内容能达到读者水平，其内容就会显得更加成熟，而不仅仅是说明内容。
难以持续进行易用性测试的做法往往在于解决问题。在内容开发过程中，即使进行任何测试，也只进行一次测试实在是太常见了。定期进行易用性测试有助于推动内容的叙事。我希望与 Matplotlib 社区制定一个时间表或定期进行易用性测试。
总结
我在空闲时间略有使用 Python 和 Matplotlib 的经验。过去几个月里，我学到的知识很多，都是基于当前文档的支持以及我自己的好奇心。那时候，我也收获过一些视频和导师。随着我开设自己感兴趣的编程课程，我仍有很多学习和改进空间。
在看到 Matplotlib 和社区对 GSoD 的想法之后，我认为提升自己作为技术文档工程师的技能并有机会向幕后学习更多知识，会是一次非常棒的体验。我觉得这个 Matplotlib 项目既有意义，也是我在意识形态中热衷的。
在完善使用指南的过程中，作为技术文档工程师，我的目标是帮助用户完成他们想要的任务，同时又不会因可用的功能而感到无所适从。我相信，最好的文档应不断发展壮大并适应用户需求，并允许任何用户自行找到解决方案。