本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- SciPy
- 技术文档工程师：
- mkg33
- 项目名称：
- 面向用户的文档和全面的结构调整
- 项目时长：
- 标准时长（3 个月）
Project description
动机：
我打算重构现有文档，以便具有不同需求的用户能够轻松访问相应文档。不言而喻，研究人员很可能对高级和细微的功能感兴趣，而没有事先掌握相关专业知识的用户则喜欢分步指南和图表。
我有兴趣出于个人和职业原因参与这个项目：首先，我想为 SciPy 做大贡献，因为我自己的研究大大受益于它；其次，在其他软件中我经常遇到文档不足（或缺乏）的情况，并且我一直想知道，如果有全面的指南，用户能够学会如何使用代码的速度有多快（如果确实如此！）。
目标：
我的目标是从内容和图形方面改进现有的 SciPy 文档。为解决这一问题，我所采取的方法最重要的一个功能是部署和分析用户调查，也就是说，这是一个在线进行的简明调查，可让不同用户表达他们对文档的需求。我坚信他们的意见应该成为灵感来源（我们还可以怎样编写更人性化的文档？）。
关于项目本身的实现，第一阶段包括设计和分析用户调查问卷，以及解决我在当前文档中发现的几个风格问题。例如，缺乏一致性（例如：二维数组与二维数组一起出现）、应该重写的复杂句子，或者某些子页面中缺少字母顺序。第二阶段的重点是推出包含相关主题的超链接的图片指南（根据调查结果和其他社区请求）。从长远来看，我希望获得为不同类型的用户量身定制的令人满意的文档。此外，我将尝试使教程在语言上和结构上更加一致。最后但同样重要的一点是，我打算根据当前社区的需求编写新的教程。
用户问卷调查：
关于用户问卷调查，我提议使用 Google 表单是出于多种原因。首先，Google 表单完全免费，且功能不限（回复者数量、问题数量等），其直观的表单非常吸引人，还有最实用的调查问卷选项（例如，可定制的线性刻度、多选题和多选题），最重要的是，还可以轻松导出结果以用于统计分析。在线调查结果显示，至少就目前而言，Google 表单是最好的免费问卷调查工具。从不太严肃的角度来说，在 Google 运营的计划中使用 Google 产品是一个不错的选择。
我已创建了包含示例问题的初步调查（调查网址为：https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform）。最终版本中的问题数量合理应介于 10 到 15 之间。为了获得实质性的结果，我建议我们主要使用单选题、线性量表和一些复选框。但线性刻度不应与完整频谱相似（这只会引起混淆，而结果很可能是高度分散的）。最多只能设置两个开放式问题，否则结果将是高度分散的，毫无帮助。我认为，即使回答数量非常多，也不会出现问题，因为数据可通过统计软件轻松导出和分析。假设回复的数量确实非常多，分析开放式问题可能会耗费一些时间，但我不会感到压力重重。毕竟，普通用户不太可能写一篇关于文档状态的文章。在最糟糕的情况下，有些答案可能会被直接存储起来，以备日后分析。
图形指南：
我对图形指南（旨在用作导航工具）的愿景基于一个流行的前提，即（大多数）人类更擅长处理简单的视觉结构，而不是单纯的文本信息。此外，毫无疑问，一张以主题为导向的示意图，包含用线将相似的兴趣主题联系起来，这无疑对于经验不足的用户来说是非常重要的资产（不仅如此）。
关于实现细节，我建议使用 TikZ 软件包。首先，它是一款功能强大的工具，似乎不存在很快被弃用的风险。它还提供高质量的输出，拥有非常可靠的文档，并且是 TeX StackExchange 和其他主流论坛上的常见主题。最重要的是，由于存在各种软件包，并且针对在 HTML（例如 TeX4ht）中嵌入 TikZ 图片进行了修复，将 TikZ 文件（更确切地说是其中包含的众多超链接）与 HTML 文档集成似乎不会造成重大问题。
例如，使用 Overleaf（用于促进协作并提供即时预览）和我将提供的预定义模板，可以轻松地解决 SciPy 中指南的未来维护问题。基本上，各图形指南之间不太可能有很大差别。结构、调色板和形状或多或少是不变的，因此后续的重新塑形和进一步自定义将不是问题。
（请在共享的 GSoD 文件夹中查看完整的提案版本。）