本页详细介绍了 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 中嵌入 TikZ 图片的各种软件包和修复程序（例如 TeX4ht），因此将 TikZ 文件（更确切地说，其中的众多超链接）与 HTML 文档集成似乎不会造成严重问题。
例如，通过使用 Overleaf（促进协作并提供即时预览）和我提供的预定义模板，可以轻松解决今后在 SciPy 中维护指南的问题。基本上，这些图形指南之间不会有很大差异。结构、调色板和形状或多或少会保持不变，因此后续的重新调整形状和进一步自定义不会出现问题。
（请参阅完整版提案，该提案位于共享的 GSoD 文件夹中。）