本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- NumPy
- 技术文档工程师：
- cooperrc
- 项目名称：
- 面向社区教育的 NumPy 文档
- 项目时长：
- 标准时长（3 个月）
Project description
简介
NumPy 是一个免费的开源软件库，可提供基于数组的简洁快速计算。它是 SciPy 堆栈中用于科学计算的基础软件包 [1]。超过 37 万个项目在使用它进行高效的数组计算 [2]。NumPy 用户会看到一个新网站，其中包含申请和案例研究 [1]。当新用户找到文档页面时，会看到多个“从这里开始”链接和入门教程，这些内容对于初学者来说可能过于繁杂，例如 NumPy 基础知识/字节交换。我从 10 年前在研究生院时就开始使用 NumPy。我发现自己在拼凑博文、讲义和 StackExchange 解答，以避免阅读 NumPy 文档。目前，StackExchange 上有超过 36 万个与 NumPy 相关的对话。我想其他用户在 NumPy 中也有类似的成功之路。教育工具的构成要素是沟通和社区 [4]。该文档需要建立一个反映项目预期目标的社区。文档应为新用户提供一致、清晰的指南。这些教程应为新用户提供易于完成的步骤，并让用户熟悉该库 [3]。该文档应欢迎新用户加入 NumPy 社区。文档的结构、节奏和作者都需要营造一个鼓励探索和沟通的环境。此提案将整理并填补当前 NumPy 文档中的空白，以便为新用户提供指导并欢迎他们加入社区。
用户传达的知识是通过测试和实验获得的 [4,5]。知识取决于测试和评估方法。在教程中提供明确目标和应用的内容，可让用户测试和评估新想法和方法。社区可以建立知识库，提高技能、事实和应用的能力。操作指南空间具有双重优势。首先，新用户和有经验的用户都有一组明确的目标来测试和构建实验。其次，潜在的文档贡献者可以在此平台上沟通其目标、方法和解决方案。如何使用区填补了新用户和可能的贡献者更容易访问 NumPy 文档的迫切需求。当前知识
约翰·杜威说，学习的基础在于真实的体验 [4]。NumPy 社区拥有大量可与其他用户分享的真实经验。教育建立在社区和沟通之上。经过整理的文档页面让新用户能够轻松体验 NumPy。它还创建了一个结构化模板，供潜在贡献者传达在 NumPy 中的使用体验。
软件文档大致分为四个领域 [3]：教程领域、方法领域、说明领域和参考领域。NumPy 文档中的教程部分包含许多文档，这些文档将说明和操作方法内容混合到教程中。教程空间应着重于用户指导，并使用简单易重复的步骤来传达想法。HowTo 空间提供更多面向目标的过程，用户可以在实际应用中应用这些过程。解释空间提供了每个函数中的详细文档字符串的详细信息。目前的教程和方法区不明确划分，有时会进入说明和参考区。“绝对初学者”中有一份很棒的教程，而“面向 Matlab 用户的 Numpy”中有关于构建 NumPy 代码的绝佳参考。清楚地划分这四个空格可让文档更加清晰易懂。
知识库中存在的缺口/未满足的需求
目前的文档涵盖了许多必要的主题，但在教程、方法、说明和参考区域之间缺乏明确的区分。这会让潜在贡献者感到困惑。新用户可能会被教程部分的说明和参考资料淹没，而潜在贡献者在贡献时也会遇到障碍。我建议为新手和可能的文档贡献者提供更易于访问的布局，并在文档中提供合理的流程，以及为新贡献者管理用户贡献的操作方法文档的拉取请求。我的长期目标是打造文档社区，让从文档中学习成为一种互动式教育和沟通体验。这种文档模型将为新加入者和潜在贡献者提供实际经验指导。
理由
这份 Google 文档之夏提案对我的教学和职业目标至关重要。我在所有课程中都使用 NumPy 和 SciPy。目前的文档对我的学生来说很难浏览。我想利用自己的经验教导非 CS 专业学生编写代码，以帮助整理、编辑和填补当前教程中的空白。然后，我可以将文档用作课程的教科书和参考资料。我使用 Python 和
具体目标
我为此 Google 文档之夏提案设定了三个具体目标：1. 整理当前文档，2. 修改当前的教程（新手入门、数组创建、编号、线性代数和 Matlab 中的 NumPy），将参考信息移至“说明空间”，与学生一起制作操作指南材料。每个具体目标都有相应的预期方案成效。
这三个具体目标旨在让新用户更容易上手使用文档，并为潜在贡献者提供结构化信息。这些目标还有助于进一步实现持续壮大 NumPy 文档社区的长期目标。预期结果
我有三种预期结果，比如：1. 经过修改的文档网页，其中明确划分了四个区域：教程、方法、说明和参考；2. 新增了以下教程：读取和写入数组、数组创建（np.zeros、np.ones、np.block 等）以及 NumPy 中的元素级运算与线性代数运算；3. 精选了方法区域。
这些预期结果将帮助新用户顺利阅读文档，为潜在的文档贡献者提供清晰的样式和格式，使当前的教程更短、更易于遵循，并将说明移至单独的部分，这样新的文档贡献者便无需构建整个 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)（写入：中等优先级）
- 使用 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 构建网页并定义并关联四个聊天室 10/1 将当前教程移至适当的聊天室并构建文档 10/10 向 GitHub 提交包含建议更改的 PR 11/1 回复评论/建议并修改 PR 正在进行，并与结果 2 相关 网站已修改 11/30
结果 2：修改教程 提交日期 审核教程修订版本排名 9/21 将当前教程内容拆分到教程和说明空间 10/1 写入排名 1：读取/写入数组 10/10 向 GitHub 提交 PR 以进行分离和修订 10/20 编写排名 1：元素/创建排名 3 线性操作 1：数组/创建排名 5 写 1
建议的教程修订排名（可能会根据导师/社区的意见而发生变化）：
读取/写入数组当前为空的页面
数组创建 (np.zeros、np.ones、np.block 等)不存在：可帮助新用户说明和演示常用的数组创建/互动工具
元素级和线性代数运算（+、-、*、/ 和 +,-@,linalg.solve）不存在：这对 1. Matlab 用户和 2. 采用线性代数（机器学习、线性回归等）的用户
结果 3：精选的 HowTo 空间 交付日期 外部链接（问题/示例）
制作方法指南示例（候选版：如何查找吉他弦的自然频率 10/20）
为新贡献者构建 HowTo 模板（10/1 进行中） 教程模板 公关和框架 （公关和框架）可能的贡献 - 与其他贡献者合作，建立社区 UContu 笔记本成员状态。
预期显著性
此 Google 文档之夏提案将编写 NumPy 文档，填补网站上缺少的教程，并招募文档贡献者。作为机械工程教授，我计划以一种方式细分文档，以便学生能够浏览文档，并轻松找到入门教程和实操操作指南。分段文档：教程、方法、参考文档和说明将为潜在贡献者提供结构化示例，以便他们构建新资源。提议的文档通过为新用户和老用户提供指导和沟通体验，让他们可以自由选择是否接受。我们建议为康涅狄格大学的学生提供有关如何撰写建议文档的指导，以便将这种教育和沟通理念付诸实践。我们希望所有用户都能找到实验、学习和加入 NumPy 社区的空间。
参考
- NumPy.org 网站于 2020 年 7 月访问。
- NumPy GitHub 代码库。
- 文档系统。Divio.com，访问日期：2020 年 7 月。
- Dewey, John. 民主与教育。Project Gutenberg，2015 年 8 月。
- Dewey、John。Quest for Certainty George Allen And Unwin Limited. 2005 年 6 月。