NumPy プロジェクト

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

プロジェクトの概要

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

プロジェクトの説明

はじめに

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

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

John Dewey 氏は、学びの基盤は純粋な経験であると述べています [4]。NumPy のコミュニティには、他のユーザーとも共有できる実体験が豊富にあります。教育はコミュニティとコミュニケーションを基盤としています。整理されたドキュメント ページは、新規ユーザーにとって NumPy の使い道を明確にしたものです。また、コントリビューター候補が NumPy での経験を伝達するための構造化テンプレートも作成されます。

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

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

現在のドキュメントでは必要なトピックが数多く取り上げられていますが、チュートリアル、ハウツー、説明、リファレンス スペースが明確に区別されていません。その結果、寄与者に混乱が生じます。新規ユーザーはチュートリアル セクションの説明や参考資料に圧倒され、コントリビューターになりそうなユーザーはコントリビューションへのハードルに直面します。ドキュメントに論理的なフローを持たせ、新しいコントリビューターによるユーザー提供のハウツー ドキュメントの pull リクエストを管理する、初心者やドキュメントのコントリビューターとなる可能性のある人のために、よりアクセスしやすいレイアウトを提案します。私の長期的な目標は、ドキュメント コミュニティを構築し、ドキュメントから学び、教育とコミュニケーションのやり取りができるようにすることです。この文書化モデルは、新規参加者や潜在的なコントリビューターの実際の体験に基づいて教育を行います。

根拠

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

具体的な目標

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

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

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

これらの期待される成果は、新規ユーザーがドキュメントを進めたり、明確なスタイルとフォーマットでドキュメントの投稿者になりやすくしたり、現在のチュートリアルを短くわかりやすいものにしたり、説明を別のセクションに移動したりします。また、新しいドキュメントの投稿者は、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 リクエストとして提出用に作成されます。ウェブサイトの修正と「配列の読み取り/書き込み」チュートリアルを見直す中で、NumPy の関数（np.ones、np.zeros、np.diag など）を使って配列を作成するためのチュートリアルを書き始めます。残りの時間は、pull リクエストの問題に対処し、ランク 3 のチュートリアル（Python での要素単位と線形代数演算）の作成を開始します。

3 つ目の成果は、コネチカット大学の学生に、numpy-tutorials リポジトリにドキュメントを作成するようアドバイスすることです。提出するチュートリアルやハウツー ドキュメントは、NumPy を使用してエンジニアリングの問題を解決する Jupyter ノートブックになります。コースのメモや例をいくつか使用して、サンプルのノートブックを提出します。テンプレートと枠組みを作成する際は、そのレイアウトと構成に従うよう生徒にアドバイスします。この成果により、生徒は実体験を通じて、コンセプトや解決策を幅広い対象者に伝えることができます。これは、学生が NumPy のコミュニティに関わって学習する絶好の機会です。

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

結果 2: チュートリアルの改訂 成果物 / 提出日 チュートリアルの改訂ランキング 9/21 現在のチュートリアル コンテンツをチュートリアルと説明のスペースに分ける 10/1 ランク 1: 配列の読み取り / 書き込み 10/10 分割と修正のために PR を GitHub に送信 10/20

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

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

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

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

成果 3: キュレートされたハウツーのスペース 成果物の時期 外部リンク（問題 / 例） ハウツーの例の作成（候補: ギターストリングの自然な周波数を見つける方法 10/20）
新規コントリビューター向けのハウツー テンプレートの作成 10/1 進行中

予想される影響

この 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。Quest for Certainty George Allen And Unwin Limited2005 年 6 月