NumPy プロジェクト

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

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

プロジェクトの説明

はじめに

NumPy は、無料のオープンソース ソフトウェア ライブラリで、配列ベースの計算をクリーンで高速に実行します。これは、科学計算用の SciPy スタックにおける基本的なパッケージです [1]。37 万を超えるプロジェクトで、効率的な配列計算に使用されています [2]。NumPy ユーザーには、アプリケーションとケーススタディを掲載した新しいウェブサイトが提供されています [1]。新規ユーザーがドキュメント ページにアクセスすると、複数の「ここから始める」リンクと、NumPy の基本やバイトスワップなど、初心者にとって圧倒的な量の入門チュートリアルが表示されます。私は 10 年前に大学院で NumPy の使用を開始しました。NumPy のドキュメントを読むのは避け、ブログ投稿、講義のメモ、StackExchange の回答をつなぎ合わせていました。現在、NumPy を扱う StackExchange の会話が 36 万件以上あります。NumPy で成功を収めた他のユーザーも、同様のルートを辿ったと思います。教育ツールの構成要素は、コミュニケーションとコミュニティです [4]。ドキュメントでは、プロジェクトの目標を反映したコミュニティを構築する必要があります。ドキュメントは、新しいユーザーにとって一貫性があり、わかりやすいガイドである必要があります。チュートリアルでは、新規ユーザーが簡単に操作できる手順を説明し、ライブラリに慣れ親しんでもらう必要があります [3]。このドキュメントは、NumPy コミュニティに新規ユーザーを歓迎する内容となっています。ドキュメントの構造、ペース、作成者は、探索とコミュニケーションを歓迎する場を作り出す必要があります。この提案では、現在の NumPy ドキュメントのギャップを整理して埋め、新規ユーザーがコミュニティに歓迎されるようにします。

ユーザーが伝える知識は、テストや実験によって得られます [4,5]。知識は、テストと評価の方法によって異なります。ハウツーに明確な目標と応用を示すコンテンツがあれば、ユーザーは新しいアイデアや方法をテストして評価できます。コミュニティは、スキル、事実、アプリケーションを強化するナレッジベースを構築できます。How-to スペースには 2 つのメリットがあります。まず、新規ユーザーと経験豊富なユーザーは、テストとテストの作成に関する明確な目標を持っています。2 つ目は、ドキュメント作成の候補者が、目標、方法、解決策を共有できるスペースがあることです。方法のスペースは、新しいユーザーやコントリビューター候補が NumPy のドキュメントに簡単にアクセスできるようにする、差し迫ったニーズを満たします。現在の知識

ジョン・デューイーは、学びの基礎は本物の経験であると言っています [4]。NumPy コミュニティには、他のユーザーと共有できる膨大な量の真の経験があります。教育はコミュニティとコミュニケーションの上に成り立っています。整理されたドキュメント ページにより、新規ユーザーが NumPy を体験しやすくなります。また、潜在的なコントリビューターが NumPy での経験を伝えるための構造化テンプレートも作成します。

ソフトウェア ドキュメントには、チュートリアル スペース、方法スペース、説明スペース、リファレンス スペースの 4 つのスペースがあります。NumPy のドキュメントには、チュートリアル スペースに説明と方法のコンテンツが混在する多くのドキュメントがあります。チュートリアルのスペースは、ユーザー教育に重点を置き、繰り返しやすい手順を使用してアイデアを伝えます。How-to スペースでは、ユーザーが実際のアプリケーションに適用できる目標指向の手順が提供されています。説明スペースには、各関数の詳細なドキュメント文字列が表示されます。現在のチュートリアルとハウツーのスペースは明確に区切られておらず、説明スペースや参照スペースに入ることがあります。「初心者向け」の優れたチュートリアルと、Matlab ユーザーが NumPy コードを構築するための優れたリファレンス「Matlab ユーザー向けの Numpy」があります。これらの 4 つのスペースを明確に区別することで、ドキュメントがより明確になります。

ナレッジベースのギャップ/アンメットニーズ

現在のドキュメントでは、必要なトピックの多くを扱っていますが、チュートリアル、方法、説明、リファレンスの各セクションが明確に区別されていません。これにより、潜在的なコントリビューターが混乱することになります。新しいユーザーは、チュートリアル セクションの説明や参考資料に圧倒され、貢献を検討しているユーザーは、貢献のハードルに直面します。ドキュメントの論理的なフローと、ユーザー提供のハウツー ドキュメントに対する新規の寄稿者による pull リクエストの管理が可能な、新規参入者やドキュメント寄稿者になり得る人にとって利用しやすいレイアウトを提案します。私の長期的な目標は、ドキュメントから学ぶことが、双方向の教育とコミュニケーションの経験となるように、ドキュメント コミュニティを構築することです。このドキュメント モデルにより、新規ユーザーや潜在的なコントリビューターは実際の経験に基づいて学習できます。

根拠

この Google Summer of Docs の提案は、私の教育とキャリアの目標にとって重要です。私はすべてのコースで NumPy と SciPy を使用しています。現在のドキュメントは生徒にとって使いづらいです。CS 専攻以外の生徒にコーディング方法を教えた経験を活かして、現在のチュートリアルの整理、編集、ギャップを埋めたい。そして、そのドキュメントを教科書や自分のコースの参考資料として利用できます。私は、Python と を使用して、数十のチュートリアル、演習、例を作成しました。一部の資料をチュートリアルやハウツーに変換したいと思っています。これまでに 800 人を超える生徒が NumPy（Scipy スタックの一部として）を使っています。秋の学期にドキュメント寄稿者になることに関心がある生徒も何人かいます。私はコネチカット大学の機械工学科で 4 年間教鞭をとり、30 単位以上のコースを担当しました。

具体的な目標

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

これらの 3 つの具体的な目標は、新規ユーザーにとってより親しみやすいドキュメントにし、潜在的なコントリビュータに構造を提供することを目的としています。また、NumPy のドキュメント コミュニティを成長させ続けるという長期的な目標の実現にも役立ちます。期待される成果

想定される結果は次の 3 つです。1. チュートリアル、ハウツー、説明、リファレンスの 4 つのスペースを明確に分離したドキュメントのウェブページを改訂、2. 配列の読み取りと書き込み、配列の作成（np.zeros、np.ones、np.block など）、NumPy の要素別と線形代数演算、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. 方法:

  • 高次元配列の線形代数（見出しと説明を編集し、タイトルを「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 関数を使用して配列を作成するためのチュートリアルの作成を開始します。残りの時間は、プルリクエストの問題に対応し、ランク 3 チュートリアル「Python での要素ごとと線形代数演算」の作成を開始します。

3 つ目の成果は、コネチカット大学の学生に numpy-tutorials リポジトリにドキュメントを作成するよう助言することです。送信されるチュートリアルまたはハウツー ドキュメントは、NumPy を使用してエンジニアリングの問題を解決する Jupyter ノートブックです。コースのノートやサンプルのいくつかを使用して、サンプル ノートブックを提出します。テンプレートとフレーミング スキームを作成する際には、レイアウトと構造に沿って作成するよう生徒にアドバイスします。この成果は、受講者がコンセプトやソリューションを幅広いオーディエンスに伝えられる、確かな経験をもたらします。これは、生徒が NumPy コミュニティに参加して学習する絶好の機会です。

成果 1: ウェブサイトの改訂 納品日 リポジトリをフォークし、Sphinx でドキュメントを作成 9 月 21 日 4 つのスペースを定義してリンクしたウェブページを作成 10 月 1 日 現在のチュートリアルを適切なスペースに移動してドキュメントを作成 10 月 10 日 提案された変更を含む PR を GitHub に送信 11 月 1 日 コメントや提案に返信し、PR を改訂 成果 2 と並行して継続 11 月 30 日 ウェブサイトの改訂 11 月 30 日

成果 2: チュートリアルの改訂 納品日 チュートリアルの改訂ランキングの確認 9 月 21 日 現在のチュートリアル コンテンツをチュートリアルと説明のスペースに分割 10 月 1 日 ランク 1: 配列の読み取り / 書き込みを記述 10 月 10 日 分離と改訂のために GitHub に PR を送信 10 月 20 日 ランク 2: 配列の作成 PR を記述 11 月 15 日 ランク 3: 要素ごとの演算と線形代数演算の PR を記述 11 月 30 日

チュートリアルの改訂版の提案ランク（メンター/コミュニティによって変更される可能性があります）:

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

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

  3. 要素ごとの演算と線形代数演算（+、-、*、/、+、-@、linalg.solve）は存在しません。これは 1 に特に役立ちます。Matlab ユーザーと 2. 線形代数（機械学習、線形回帰など）を採用している人

成果 3: キュレートされたハウツー スペース 納品日 外部リンク（問題 / 例） ハウツーの例を作成する（候補: ギターの弦の自然な周波数を見つける方法 10 月 20 日
新しいコントリビューター向けのハウツー テンプレートを作成 10 月 1 日進行中 チュートリアル テンプレートの PR と、可能な貢献のフレーミング 他のコントリビューターと協力して、UConn の学生やその他のコミュニティ メンバーを募集するハウツー ノートブックを作成 7 月 1 日ステータス: 課外活動が承認され、申請が届いています

予想される重要性

この Google Summer of Docs の提案では、NumPy のドキュメントを作成し、ウェブサイトに不足しているチュートリアルを追加し、ドキュメントのコントリビューターを増やす予定です。機械工学の教授として、学生がドキュメントを操作し、ハンズオン ガイドではなく入門チュートリアルを簡単に見つけられるように、ドキュメントを分割する予定です。チュートリアル、ハウツー、リファレンス、説明など、分割されたドキュメントにより、新しいリソースを構築するための構造化された例をコントリビューターに提供できます。提案されたドキュメントは、新規ユーザーと経験豊富なユーザーにとって、教育とコミュニケーションの体験を通してギブ アンド テイク エクスペリエンスを提供するものです。コネチカット大学の学生への助言に関する提案されている方法書では、この教育とコミュニケーションの考え方を実践しています。すべてのユーザーが NumPy コミュニティで試行錯誤し、学び、参加できる場を提供したいと考えています。

参照

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