NumPy 项目

本页面包含“Google 文档季”接受的技术写作项目的详细信息。

项目摘要

开源组织：
NumPy
技术文档工程师：
Cooperrc
项目名称：
关于社区教育的 NumPy 文档
项目时长：
标准时长（3 个月）

Project description

简介

NumPy 在免费的开源软件库中提供干净且基于数组的快速计算。它是 SciPy 堆栈中用于科学计算的基本软件包 [1]。超过 37 万个项目用于高效数组计算 [2]。新网站会欢迎 NumPy 用户，该网站提供了应用和案例研究 [1]。当新用户找到文档页面时，他们会看到多个“从这里开始”链接和入门教程，比如 NumPy 基础知识/字节交换，这些链接和入门教程可能会让新手不堪重负。十年前，我从一所研究生院就开始使用 NumPy。我把博文、讲座笔记和 StackExchange 答案拼凑在一起，不去查阅 NumPy 文档。目前有超过 36 万个涉及 NumPy 的 StackExchange 对话。我想其他用户也有类似的 NumPy 获得成功的途径。教育工具的基本组成部分是沟通和社区 [4]。本文档需要建立一个反映项目的预期目标的社区。这些文档应针对新用户提供一致且清晰的指南。这些教程应向新用户提供简单易学的步骤，并让他们能够熟练使用库 [3]。本文档应欢迎新用户加入 NumPy 社区。结构、节奏和文档作者都需要创建一个欢迎探索和交流的地方。此方案将整理并填补当前 NumPy 文档中的不足，以便新用户获得教育并欢迎加入社区。

通过测试和实验，获得用户沟通的知识 [4、5]。知识的掌握情况取决于测试和评估方法。内容中提供了清晰的目标和应用方法，以便用户测试和评估新的想法和方法。社区可以建立知识库，以增强技能、提高事实和应用能力。HowTo 空间具有双重优势。首先，新用户和经验丰富的用户都有一系列明确的目标来测试和构建实验。其次，潜在的文档贡献者有空间来传达他们的目标、方法和解决方案。HowTo 领域是迫切需要，让新用户和潜在贡献者能够更方便地访问 NumPy 的文档。 当前知识

约翰·杜威表示，学习的基础是真实的体验 [4]。NumPy 社区提供了大量可以与其他用户分享的真实体验。教育是建立在社区和沟通的基础之上。文档页面井然有序，为新用户提供了一种体验 NumPy 的途径。此外，它还为潜在贡献者创建了一个结构化模板，用以在 NumPy 中传达经验。

软件文档 [3] 空间大致分为四个部分：教程空间、操作方法空间、说明空间和参考空间。NumPy 文档在教程空间中包含许多文档，将说明和方法指南的内容混合到教程中。教程空间应侧重于用户指导，并使用易于重复的步骤来传达想法。HowTo 空间提供了更多以目标为导向的流程，用户可以在实际应用程序中应用这些过程。说明空间提供了每个函数中详细的文档字符串信息。当前的教程和方法指南部分未明确划分，有时会加入说明和参考空间。“绝对初学者”教程中有一个非常不错的教程；“面向 Matlab 用户的 Numpy 说明”中，对于 Matlab 用户构建 NumPy 代码提供了很好的参考资料。明确地划分这四个空间可以让文档更加清晰。

知识库中的缺口/未满足的需求

当前文档涵盖了许多必要的主题，但教程、操作方法、说明和参考内容之间并未明确区分。这会让潜在贡献者感到困惑。教程部分的说明和参考资料可能会让新用户感到不堪重负，潜在贡献者在贡献内容方面也会遇到障碍。我提出了一种面向新开发者和可能的文档贡献者的更易于访问的布局，该布局具有合理的文档流程，并管理新贡献者对用户提供的 HowTo 文档的拉取请求。我的长期目标是建立文档社区，让从文档中学到的知识是一种接受教育和沟通的体验。这种记录模型将以培训新人和潜在贡献者的实际经验为基础。

理由

这个 Google 文档之夏提案对我的教学和职业目标来说非常重要。我在所有课程中都使用了 NumPy 和 SciPy。学生浏览当前文档非常困难。我想利用我教非 CS 专业学生编写代码的经验，帮助组织、编辑和填补当前教程中的空白。然后，我可以将这些文档用作课程的教科书和参考资料。我已使用 Python 和 创建了数十个教程、练习和示例。我想将其中部分资料转换为教程和方法指南。我有 800 多名学生使用 NumPy（作为 Scipy 堆栈的一部分），还有多名学生有兴趣成为秋季学期的文档贡献者。我在康涅狄格大学机械工程专业教授了 4 年，教授了超过 30 个学分的课程。

具体目标

对于此次 Google 文档之夏提案，我有三个具体目标：1. 整理当前文档；2. 修改当前教程（新手指南、数组创建、索引、线性代数和 NumPy for Matlab），将参考信息移至说明空间； 3. 与学生一起制作操作指导材料。每个具体目标都有针对提案的预期结果。

这三个具体目标旨在让本文档更受新用户欢迎，并为潜在贡献者提供结构性参考。这些目标还有助于进一步实现持续发展 NumPy 文档社区的长期目标。预期成果

我有三种预期结果，如下所示：1. 经过修订的文档网页，明确区分了以下四个空间：教程、方法指南、说明和参考；2. 新教程：读取和写入数组、数组创建（np.zeros、np.ones、np.block 等），以及 NumPy 中的元素对应与线性代数运算；以及 3. 精选的 HowTo 空间。

这些预期成果将帮助新用户逐步了解文档，为潜在的文档贡献者提供清晰的样式和格式，简化当前教程，简化当前教程，将说明移到单独的部分，而新的文档贡献者将能够在方法部分贡献小型用例，而无需构建完整的 Sphinx 文档。我们希望继续打造我们的教与学社区。

新的文档贡献者可以在不构建整个 Sphinx 文档的情况下，为数百万用户提供小型用例。我们希望继续打造我们的教与学社区。建议的文档将模仿 Matplotlib、Divio 等当前的开源文档。新用户和潜在贡献者将可以更轻松地学习将 NumPy 应用到自己的领域和软件中。

该项目的时间安排为 9 月 14 日至 11 月 30 日。第一步是构建文档，并将当前教程中的内容拆分为教程内容、操作方法和说明内容。这项工作将在该项目的前五周完成，并分别作为网站和教程的成果 1 和 2 的一部分。提议的文档组织方式如下方提议的文档所示。

建议的文档：

i.Tutorials:

  • 初学者的绝对基础知识（移除安装，可以用 numpy.loadtxt 替换 pandas 导入/导出吗？）
  • “什么是 numpy”链接
  • 点击此链接可查看基本安装说明
  • 快速入门教程（旨在跟进 Python 教程）
  • 使用 NumPy 数组
  • 数组创建（np.zeros、np.ones、np.block 等）（写入：中低优先级）
  • 元素级运算（+、-、*、/）和线性代数运算（+、-、@、linalg.solve）（write:med 优先级）
  • 使用 Numpy 读取和写入数据（写入：高优先级）
  • 索引编制

ii. 方法指南：

  • n 维数组上的线性代数（希望修改标题和说明，也许可以将标题改为“使用 Numpy 的线性代数处理图像”）
  • 指向 numpy-tutorials 操作方法内容（持续性工作）的链接

iii. 说明：

  • 数据类型
  • 使用 Numpy 执行 I/O 操作
  • 索引编制
  • 正在广播
  • 字节交换
  • 结构化数组
  • 编写自定义数组容器
  • 对 ndarray 进行子类化
  • 其他

iv. 参考空间：

  • 术语库
  • Numpy API 参考
  • 面向 Matlab 用户的 Numpy（等值表是一个很好的参考表，但数组/矩阵讨论会分散注意力，并且似乎已弃用）

完成这个 Google 文档季后，我提出以下结果：

  • 修订了文档网页，明确划分了以下四个区域：“教程”、“方法指南”、“说明”和“参考”
  • 新增了以下教程：数组创建（np.zeros、np.ones、np.block 等）、元素级运算（+、-、*、/）和线性代数运算（+、-、@、linalg.solve）、使用 Numpy 读取和写入数据（高优先级）
  • 提供方法指南文档，以增加用户贡献，并帮助进一步实现社区的教与学目标

每项成效在结果 1-3 的表格中列出了一些步骤。在提交建议文档以供审核期间，高优先级“读/写数组”教程将作为拉取请求提交，作为结果 2 的一部分。在查看修订后的网站和更新“读取/写入数组”教程期间，我将开始编写一个使用 NumPy 函数（例如 np.ones、np.zeros、np.diag）创建数组的教程。剩余时间将用于响应拉取请求问题，并开始编写 3 阶教程：Python 中的元素级和线性代数运算。

第三个结果是建议康涅狄格大学的学生在 numpy-tutorials 代码库中构建文档。提交的教程或操作指南文档将是使用 NumPy 解决工程问题的 Jupyter 笔记本。我会使用部分课程笔记/示例来提交示例笔记本。我会建议学生按照版式和结构来构建模板和取景方案。此结果为学生提供了一种真实的体验，让他们能够向更广泛的受众传达概念和解决方案。这是学生参与 NumPy 社区和学习的绝佳机会。

结果 1：修改网站交付日期 使用 Sphinx 创建分支库和构建文档 9/21 使用定义并关联的 Four Space 构建网页 10/1 将当前教程移到适当的空间并制作文档 10/10 将公关建议提交到 GitHub 并提交更改建议 11/1 回复评论/建议，并持续进行修订 2 3

结果 2：修改教程交付日期 回顾教程修订排名 9 月 21 将当前教程内容分离到教程空间和说明空间 10/1 写入排名 1：读取/写入数组 10/10 提交 PR 进行分离和修订 10/20 编写排名 2：数组/排名 1 PR1：编写排名 2：编写元素排名 1 PR1

建议的教程修订版排名（可能会根据导师/社区而发生变化）：

  1. 读取/写入数组当前为空页面

  2. 数组创建（np.zeros、np.ones、np.block 等）不存在：有助于新用户了解和演示常用的数组创建/互动工具

  3. 元素级和线性代数运算（+、-、*、/ 和 +,-@,linalg.solve）不存在：这对于 1. Matlab 用户和 2. 采用线性代数（机器学习、线性回归等）的用户

结果 3：精选 HowTo 空间交付日期外部链接（问题/示例） 制作 HowTo 示例（候选人：如何确定吉他琴弦的自然频率，10 月 20 日）
为新贡献者制作 HowTo 模板 10/1

预期显著性

这项 Google 文档之夏提案将制作 NumPy 文档，填写网站上缺失的教程，并获得文档贡献者。作为一名机械工程教授，我计划按照一定的方式对文档进行细分，以便我的学生能够浏览文档，并轻松找到入门教程和实操操作指南。这一细分文档：教程、方法指南、参考文档和说明将向潜在贡献者提供结构化示例，以帮助其构建新资源。所提议的文档旨在让新用户和有经验的用户通过“教育和沟通”体验“推而广之”。面向康涅狄格大学学生提出的方法文档指导建议会将这一教育与交流理念付诸实践。我们希望所有用户都能找到实验和学习的空间，并加入 NumPy 社区。

参考编号

  1. 2020 年 7 月访问的 NumPy.org 网站。
  2. NumPy GitHub 代码库。
  3. 文档系统。2020 年 7 月访问的 Divio.com。
  4. 杜威、约翰。民主与教育。古腾堡项目，2015 年 8 月。
  5. 杜威、约翰。《Quest for George Allen and Unwin Limited》2005 年 6 月。