NumPy 项目

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

项目摘要

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

Project description

简介

NumPy 通过免费的开源软件库实现简洁、快速的基于数组的计算。它是 SciPy 堆栈中用于科学计算的基本软件包 [1]。超过 37 万个项目使用高效数组计算 [2]。新网站迎来了 NumPy 用户，那里有各种应用和案例研究 [1]。新用户找到文档页面时，会看到多个“从这里开始”链接和入门教程（例如 NumPy Basics/字节交换），这些链接和入门教程可能会让新手感到无所适从。十年前，我在研究生院开始使用 NumPy。我把博文、讲座笔记和 StackExchange 答案拼凑在一起，以免浏览 NumPy 文档。目前处理 NumPy 的 StackExchange 对话数量超过 36 万个。我想其他用户在 NumPy 中取得成功的途径也是类似的。教育工具的基本组成部分是沟通和社区 [4]。本文档需要建立一个反映项目的预期目标的社区。这些文档应针对新用户提供一致、清晰的指南。这些教程应该为新用户提供简单易懂的步骤，并让他们能够熟悉该库 [3]。本文档应欢迎新用户加入 NumPy 社区。文档的结构、速度和作者都需要创建一个欢迎探索和交流的地方。此方案将整理并填补当前 NumPy 文档中的缺口，以便新用户都有机会接受培训并加入社区。

通过测试和实验获得用户沟通的知识 [4、5]。知识取决于测试和评估方法。如果内容在方法指南中提供了明确的目标和应用，让用户能够测试和评估新的想法和方法。社区可以建立知识库，以增强技能、了解事实和应用。介绍操作方法的空间具有双重优势。首先，新用户和老用户都有明确的测试和实验目标。其次，潜在的文档贡献者可以在这里交流自己的目标、方法和解决方案。操作方法方面的内容能够立即满足新用户和可能贡献者的 NumPy 文档需求。 当前知识

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

软件文档 [3] 分为四个大致分组的空间：教程空间、操作方法空间、说明空间和参考空间。NumPy 文档在教程部分中有许多文档，其中混合了说明和操作方法空间的内容。教程空间应着重提供用户指导，并采用易于重复的步骤来传达想法。HowTo 空间提供了更多以目标为导向的过程，用户可以在实际应用程序中应用这些过程。说明空间提供了每个函数中详细的文档字符串详细信息。当前的教程和方法指南空间没有明确划分，有时会输入到说明和参考空间。“Absolute Beginner”提供了一个非常出色的教程，“Numpy for Matlab 用户”中还提供了一个很好的参考供 Matlab 用户构建 NumPy 代码。明确区分这四个空间可使文档更加清晰。

知识库中的差距/需求未满足

当前文档涵盖了许多必要的主题，但在教程、方法指南、说明和参考空间之间没有明确区分。这会给潜在贡献者造成混淆。新用户可能会因教程部分的说明和参考资料而应接不暇，而潜在贡献者在贡献内容时可能会遇到困难。我为新手和潜在的文档贡献者提出了一种更易于使用的布局，在文档中设置逻辑流程，并管理新贡献者针对用户贡献的方法文档的拉取请求。我的长期目标是建立文档社区，让从文档中学到的知识是一种“平等的教训”式的交流体验。这种文档模式将以新员工和潜在贡献者的实际体验为基础进行培训。

理由

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

具体目标

对于这个 Google 文档之夏计划，我有三个具体目标：1. 整理当前文档。2. 修改当前教程（新手指南、数组创建、索引、线性代数和适用于 Matlab 的 NumPy），将参考信息移至说明空间； 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:

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

ii. 方法指南：

  • n 维数组上的线性代数（喜欢修改标题和说明，也许可以将标题改为“Image process with Numpy’s linear algebra”）
  • 指向 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）创建数组的教程。剩余时间将用于响应拉取请求问题并开始编写 rank 3 教程：在 Python 中进行元素级和线性代数运算。

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

成果 1：修改网站交付日期 使用 Sphinx 创建分支代码库和构建文档 9/21 使用定义并关联的四个空间构建网页 10/1 将当前教程移至适当的空间，并构建文档 10/10 将 PR 提交到 GitHub，并提出更改建议 11/1 回复评论/建议，持续修改网站 23

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

建议的教程修订版本排名（可能会因导师/社区而异）：

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

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

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

结果 3：精选操作指南空间 提交日期 外部链接（问题/示例） 构建操作方法示例（候选内容：如何查找吉他弦的自然频率 10/20
为新贡献者构建操作指南模板 10/1 进行中 教程模板 PR 和框架 可能的贡献内容 与其他贡献者合作构建操作指南/学生的作业 7

预期统计显著性

这个 Google Summer of Google 文档提案将制作 NumPy 文档 ，填写网站中缺失的教程，并获得文档贡献者。作为一名机械工程教授，我计划对文档进行细分，以便我的学生能够浏览文档，并轻松找到入门教程和实操指南。拆分的文档：教程、方法指南、参考文档和说明将为潜在贡献者提供结构化示例来构建新资源。提议的文档有助于为新用户和经验丰富的用户提供教育和交流体验。与康涅狄格州大学的学生一起提出方法指南文档建议，将这一具有教育和交流理念的想法付诸实践。我们希望所有用户都能找到实验和学习的空间，并加入 NumPy 社区。

参考

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