NumPy プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:
NumPy
テクニカル ライター:
cooperrc
プロジェクト名:
コミュニティ教育向け NumPy ドキュメント
プロジェクトの期間:
標準の期間（3 か月）

プロジェクトの説明

はじめに

NumPy は、無料のオープンソース ソフトウェア ライブラリで、クリーンで高速な配列ベースのコンピューティングを提供します。これは、科学コンピューティングのための SciPy スタックの基礎となるパッケージです [1]。37 万件以上のプロジェクトで効率的な配列コンピューティングが使用されています [2]。NumPy のユーザーには、アプリケーションとケーススタディを含む新しいウェブサイトが表示されます [1]。新規ユーザーがドキュメント ページを見つけると、複数の「Start Here」リンクと入門チュートリアルが表示されます。初心者にはまず、NumPy の基本/バイトスワップなど、初心者を圧倒するような入門チュートリアルです。NumPy は 10 年前に大学院で使い始めました。NumPy のドキュメントを見なくても、ブログ投稿、講義ノート、StackExchange の回答をつなぎ合わせることができました。現在、NumPy を扱う StackExchange の会話は 36 万以上あります。NumPy で成功するまでに、同じような道のりを持つユーザーが他にいるのではないでしょうか。教育ツールの構成要素はコミュニケーションとコミュニティです [4]。ドキュメントでは、プロジェクトの望ましい目標を反映したコミュニティを確立する必要があります。ドキュメントは、新規ユーザーにとって一貫性のあるわかりやすいガイドである必要があります。チュートリアルでは、新規ユーザーが簡単に手順を進め、ライブラリを快適に利用できるようにする必要があります [3]。ドキュメントでは、NumPy コミュニティに新規ユーザーを歓迎します。ドキュメントの構成、ペース、作成者はすべて、探索とコミュニケーションを歓迎する場所を作り出す必要があります。この提案は、新規ユーザーがコミュニティで学び、歓迎されるよう、現在の NumPy ドキュメントにおけるギャップを整理して埋めます。

ユーザーがコミュニケーションする知識は、試行錯誤することで得られます [4,5]。知識は、テストと評価の方法に左右されます。ハウツーでは、目標や適用方法を明確に示すことで、ユーザーは新しいアイデアや手法を試して評価できます。コミュニティは、スキル、事実、アプリケーションを強化するナレッジベースを構築できます。ハウツーのスペースには 2 つの利点があります。まず、新規ユーザーと経験豊富なユーザーには、テストと構築に関する明確な目標があります。第二に、ドキュメントのコントリビューターとなる希望者には、目標、方法、ソリューションを伝える場があります。このハウツーのスペースは、新規ユーザーや潜在的な投稿者が NumPy のドキュメントを容易に利用しやすくしたいという差し迫ったニーズに応えるものです。現在の知識

John Dewey 氏は、学びの基盤は純粋な経験であると述べています [4]。NumPy のコミュニティには、他のユーザーと共有できる実体験が豊富にあります。教育はコミュニティとコミュニケーションを基盤としています。整理されたドキュメント ページは、新規ユーザーが NumPy を理解しやすい環境を整えています。また、潜在的な寄稿者が NumPy での経験を伝達するための構造化されたテンプレートも作成します。

ソフトウェア ドキュメントには、チュートリアル空間、ハウツー空間、説明空間、リファレンス空間の 4 つに大別されます [3]。NumPy のドキュメントは、チュートリアルのスペースに、説明とハウツーのコンテンツを混在させた多数のドキュメントで構成されています。チュートリアルの領域は、ユーザー教育に重点を置き、簡単に繰り返してアイデアを伝達できるステップを使用する必要があります。ハウツーの領域は、ユーザーが実際のアプリケーションに適用できるように、より目標に基づいた手順を提供します。説明スペースには、各関数のドキュメント 文字列に関する詳細情報が表示されます。現在のチュートリアルとハウツーのスペースは明確に区切られておらず、説明と参照のスペースに入る場合があります。「Absolute 初心者」向けの優れたチュートリアルがあり、「NumPy for Matlab ユーザー」には、Matlab ユーザーが NumPy コードをビルドする際の優れたリファレンスが用意されています。これら 4 つのスペースを明確に記述すると、ドキュメントがより明確になります。

ナレッジベースのギャップ/満たされていないニーズ

現在のドキュメントは多くの必要なトピックをカバーしていますが、チュートリアル、ハウツー、説明、参照スペースが明確に区別されていません。その結果、投稿者の混乱を招きます。新規ユーザーはチュートリアル セクションの説明や参考資料に戸惑うことがあり、コントリビューターとなる可能性のあるユーザーは、貢献するのにハードルが高いという問題を抱えています。新しいコントリビューターやドキュメント寄稿者の候補に対し、ドキュメントの論理的なフローと、新しいコントリビューターによるユーザー提供のハウツー ドキュメントの pull リクエストを管理する、より使いやすいレイアウトを提案します。私の長期的な目標は、ドキュメント コミュニティを構築し、ドキュメントから学ぶことが、教育とコミュニケーションのギブアンドテイク体験となるようにすることです。このような文書化のモデルは、新規参入業者や潜在的な投稿者の実際のエクスペリエンスにおける教育の土台となります。

背景

この Google Summer of Docs の提案は、私の教育学とキャリア上の目標にとって重要である。私はすべてのコースで NumPy と SciPy を使っています。現在のドキュメントは、生徒が操作しにくい。CS 系以外の学生にコーディング方法を教え、現在のチュートリアルの整理、編集、ギャップを埋めるために、自分の経験を活かしていきたいと考えています。その後、ドキュメントを教科書やコースの参考資料として使用できます。Python と を使用して、数多くのチュートリアル、演習、サンプルを作成してきました。この資料の一部をチュートリアルやハウツーに変換する私は 800 人以上の生徒に NumPy を（Scipy スタックの一部として）使用しており、秋学期のドキュメントの貢献者になることに興味がある生徒が複数います。コネチカット大学機械工学部で 4 年間教師に従事し、30 クレジット時間以上のコースで教えています。

特定の目標

この Google Summer of Docs の提案の具体的な目標は、次の 3 つです。1. 現在のドキュメントの整理、2. 現在のチュートリアル（初心者向けガイド、配列の作成、インデックス、線形代数、NumPy for Matlab）を編集して、参照情報を説明スペースに移動させます。3. 生徒と一緒にハウツー資料を作成します。具体的な目標ごとに、提案で期待される結果があります。

この 3 つの具体的な目的は、新規ユーザーにとってより使いやすいドキュメントにし、コントリビューターになってくれそうな人が構成できるようにドキュメントを作成することです。また、NumPy ドキュメント コミュニティの継続的な成長という長期的な目標の達成にもつながります。期待される成果

期待できる結果は次の 3 つです。1. チュートリアル、ハウツー、説明、リファレンス、2. 配列の読み取りと書き込み、配列作成（np.zeros、np.ones、np.block など）、要素単位対線形代数演算の 4 つのスペースを明確に分離したドキュメントのウェブページ、3. キュレートされたハウツーのスペース

このように期待される成果は、新規ユーザーによるドキュメントの操作、ドキュメント寄稿者への明確なスタイルと形式の提供、現在のチュートリアルを短くわかりやすいものにする、説明を別のセクションに移動するといったことに役立ちます。また、新しいドキュメントのコントリビューターは、Sphinx のドキュメント全体を作成しなくてもハウツー セクションに小規模なユースケースを投稿できるようになります。Google は、今後も教育と学習のコミュニティを構築していきたいと考えています。

新しいドキュメントのコントリビューターは、Sphinx ドキュメント全体を作成しなくても、数百万人のユーザーに小規模なユースケースに貢献できます。Google は、今後も教育と学習のコミュニティを構築していきたいと考えています。この提案ドキュメントは、Matplotlib や Divio などの現在のオープンソース ドキュメントに似せています。新規ユーザーや潜在的なコントリビューターは、自分のフィールドやソフトウェアに NumPy を適用する方法を簡単に学ぶことができます。

プロジェクトのタイムラインは 9 月 14 日～ 11 月 30 日です。最初のステップは、現在のチュートリアルのドキュメントと個別のコンテンツを、チュートリアル、ハウツー、説明コンテンツに分けることです。これは、成果 1 と成果 2 のそれぞれウェブサイトとチュートリアルの改訂の一環として、プロジェクトの最初の 5 週間に行われます。提案するドキュメント構成は、以下の推奨ドキュメントに記載されています。

推奨ドキュメント:

i.Tutorials:

  • 初心者のための絶対的な基本（インストールの削除、pandas のインポート/エクスポートを numpy.loadtxt に置き換えることはできますか？）
  • 「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 ドキュメントのこのシーズンを修了すると、次の成果が得られることを提案します。

  • 4 つのスペース（チュートリアル、ハウツー、説明、リファレンス）を明確に分離した改訂されたドキュメント ウェブページ
  • 配列の作成（np.zeros、np.ones、np.block など）、要素ごとの演算（+、-、*、/）、線形代数演算（+、-、@、linalg.solve）、Numpy を使用したデータの読み取りと書き込み（優先度高）に関する新しいチュートリアル
  • ユーザーへの貢献を増やし、教育と学習におけるコミュニティの目標の推進に役立つハウツー ドキュメントについてアドバイス

各成果には、成果 1 ～ 3 の表で概説している、いくつかのステップがあります。提案されたドキュメントが審査のために提出されている間、優先度の高い「配列の読み取り/書き込み」チュートリアルは、成果 2 の一部として pull リクエストとして提出用に記述されます。改訂したウェブサイトのレビューと「配列の読み取り/書き込み」チュートリアルの更新の中で、np.ones、np.zeros、np.diag などの NumPy の関数を使用して配列を作成するためのチュートリアルを書き始めます。残りの時間は、pull リクエストの問題に対処し、ランク 3 のチュートリアル（Python での要素単位と線形代数演算）の作成を開始します。

3 つ目の成果は、コネチカット大学の学生に numpy-tutorials リポジトリでドキュメントを作成するようアドバイスすることです。提出するチュートリアルやハウツー ドキュメントは、NumPy を使ってエンジニアリングの問題を解決する Jupyter ノートブックになります。コースメモ/例の一部を使用して、サンプル ノートブックを提出します。テンプレートと枠組みを作る際に、このレイアウトと構造に従うよう生徒にアドバイスします。このテストの結果は、生徒が概念や解決策を幅広いオーディエンスに伝えるための実体験に基づいたものになります。これは、学生が NumPy のコミュニティに関わり、学ぶ絶好の機会です。

成果 1: ウェブサイトの提出日を修正 Sphinx 9/21 でフォーク リポジトリとドキュメントを構築 Sphinx 9/21 でフォーク リポジトリとドキュメントを作成する 4 つのスペースを定義してリンクされたウェブページを構築する 10/1 現在のチュートリアルを適切なスペースに移動してドキュメントを作成する 10/10 変更を提案して GitHub に PR を提出する 11/1 ウェブサイトに対するコメント/提案への対応と PR の改訂

成果 2: チュートリアルの改訂 成果物の提出日 チュートリアルのリビジョン ランキングを確認する 9/21 現在のチュートリアル コンテンツをチュートリアルと説明のスペースに分離する 10/1 ランク 1: 配列の読み取り / 書き込み 10/10 分離とリビジョンのために PR を GitHub に送信 10/20 ランク 2: 配列作成 1 要素 PR 11/

チュートリアル改訂のランキング案（メンター/コミュニティに応じて変わる可能性があります）:

  1. 現在の空のページの読み取り/書き込み配列

  2. 配列の作成（np.zeros、np.ones、np.block など）存在しない: 新規ユーザーに、一般的な配列作成/操作ツールについて説明し、デモを行うのに役立ちます。

  3. 要素単位および線形代数演算（+,-,*,/ および +,-@,linalg.solve）は存在しません。特に 1 の場合に役立ちます。Matlab ユーザー、2. 線形代数（ML、線形回帰など）を採用している人

成果 3: キュレートされたハウツーのスペース 成果物の提出日 外部リンク（問題 / 例） ハウツーの例を作成する（受験者: ギター文字列の自然な周波数を見つける方法 10/20）
新規貢献者向けのハウツー テンプレートの作成 10/1 進行中 チュートリアル テンプレートの PR と 7 つの承認済み課題のフレーミング コミュニティ メンバーを募集し、他の協力者を募集する

予想される意味

この Google Summer of Docs の提案は、NumPy ドキュメントを作成し、ウェブサイトから不足しているチュートリアルを埋め、ドキュメントの貢献者を獲得することになる。私は機械工学の教授として、生徒がドキュメント内を移動し、入門チュートリアルとハンズオン ハウツーガイドを簡単に見つけられるよう、ドキュメントを分割することを計画しています。分割されたドキュメント（チュートリアル、ハウツー、リファレンス、説明）では、コントリビューターとなるユーザーが新しいリソースを構築するための構造化された例を確認できます。提案されたドキュメントは、新しいユーザーと経験豊富なユーザーが教育とコミュニケーションをとりながらのやりとりを通じて役立ちます。提案されたハウツー ドキュメントでは、コネチカット大学の学生に行うこの教育とコミュニケーションのアイデアを実践します。Google は、ユーザーの皆様が実験や学習の場となり、NumPy コミュニティにご参加いただけるようにしたいと考えています。

参照

  1. NumPy.org のウェブサイト（アクセス日: 2020 年 7 月）
  2. NumPy GitHub リポジトリ。
  3. ドキュメント システム。Divio.com に 2020 年 7 月にアクセス。
  4. Dewey、John。民主主義と教育。Project Gutenberg、2015 年 8 月。
  5. Dewey、John。『The Quest for Certainty George Allen And Unwin Limited』2005 年 6 月