本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- NumPy
- 技術撰稿人：
- cooperrc
- 專案名稱：
- 社區教育 NumPy 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
引言
NumPy 利用免費的開放原始碼軟體程式庫，提供簡潔又快速的陣列式運算技術。這是 SciPy 堆疊中用於科學運算的基本套件 [1]。超過 37 萬個專案可用於有效率地計算陣列 [2]。NumPy 使用者被新網站問候，並在其中提供應用程式和個案研究 [1]。新的使用者找到說明文件頁面時，會看到多個「從此開始」連結和簡介教學課程，這些連結和簡介教學課程對新手來說可能十分吃力，例如 NumPy Basics/byte-swaging。我在 10 年前就讀研究所開始使用 NumPy。我發現自己就是拼湊網誌文章、課堂筆記和 StackExchange 回答，避免逐一閱讀 NumPy 說明文件。目前有超過 36 萬個 StackExchange 對話處理 NumPy。我想像一下，其他使用者可能在 NumPy 中有類似的成功途徑。教育工具的構成元素是溝通與社群 [4]。說明文件必須建立能反映專案目標的社群。提供給新使用者的說明文件應一致且清楚指南。教學課程應提供簡單明瞭的步驟，並讓使用者自在地使用程式庫 [3]。這份說明文件應歡迎新使用者加入 NumPy 社群。文件的結構、節奏和作者，全都要打造一個歡迎探索及溝通交流的園地。本提案將整理並填補目前的 NumPy 說明文件中的空缺，以便為新使用者提供教育資源，並鼓勵他們參與社群活動。
使用者溝通的知識來自測試和實驗 [4,5]。實際知識取決於測試和評估方式。內容提供明確的目標和應用程式，讓使用者可以測試和評估新的想法和方法。社群成員能建立知識庫來增進技能、事實和應用程式應用。操作空間為雙重優勢。首先，新使用者和經驗豐富的使用者訂有一系列明確的目標，用於測試及打造實驗。第二，潛在文件貢獻者擁有交流目標、方法和解決方案的空間。有了操作說明空間，就可立即讓新使用者和可能的貢獻者更容易存取 NumPy 的說明文件。目前知識
John Dewey 說，學習是真正的體驗 [4]。NumPy 社群有大量真實體驗，可與其他使用者分享。教育是建立社群及溝通交流的基石。經過彙整的說明文件頁面，為新使用者提供輕鬆體驗 NumPy 的方法。這項工具也會建立結構化範本，讓潛在貢獻者在 NumPy 中傳達相關經驗。
軟體說明文件有四個廣泛分組的空間 [3]：教學課程空間、說明空間、說明空間和參考空間。NumPy 說明文件會在教學課程空間中提供許多文件，將說明和如何空間內容整合到教學課程中。教學課程空間應著重於使用者教育，並以易於重複的步驟傳達想法。操作空間提供更多目標導向的程序，讓使用者可在實際應用程式中應用。說明空間提供每個函式中詳細的文件字串資訊。目前的教學課程和操作說明聊天室並未清楚劃分，有時還會在說明和參考空間中輸入內容。「絕對新手」有個很棒的教學課程，Matlab 使用者在「Numpy for Matlab 使用者」中提供了實用的參考資源。清楚劃分這四個空間可讓說明文件更加清楚。
知識庫/缺陷需求的缺口
目前的說明文件涵蓋許多必要主題，但並未清楚地區分教學課程、操作說明、說明和參考空間。這可能會使潛在的協作者感到困惑。新手使用者在教學章節提供的說明和參考資料可能會感到不堪負荷，因此可能的貢獻者會面臨各種挑戰。我提議採取邏輯流程，讓新手和可能文件貢獻者更容易理解版面配置，同時針對新貢獻者提供的操作說明文件，管理提取要求。我的長期目標是建立說明文件社群，這樣一來從說明文件中學習就會有可用的教育和溝通經驗。這類說明文件模型可讓新觀眾和潛在貢獻者實際獲得教育體驗。
原因
這個 Google Summer of Google 文件提案對於我的教學方法和職涯目標十分重要。我在所有課程中都使用 NumPy 和 SciPy。我的學生很難瀏覽目前的文件，我想運用自身經驗，教導非 CS 大學生如何編寫程式碼，協助管理、編輯及填補當前教學課程中的缺口。接著，我可以將說明文件當做教科書和參考教材。我已經使用 Python 和
特定目標
我對這份「Google Summer of Google 文件」提案有三個具體目標：1. 整理目前的說明文件，2. 編輯目前的教學課程 (新手指南、陣列建立、索引、線性代數和 Matlab 的 NumPy)，將參考資訊移至說明空間；3. 和學生一起製作操作說明教材。每個具體目標都有預期結果。
這三項具體的目標，是要讓這份說明文件對新使用者更友善，並為潛在的貢獻者提供架構。這項計畫的目的也有助於進一步發展 NumPy 說明文件社群，藉此實現長期目標。預期成果
預期成果有三種，例如：1. 修訂說明文件網頁，清楚區分四個空間：教學課程、教學示範、說明和參考資料。2. 全新教學課程：讀取和寫入陣列、建立陣列 (np.zeros、np.ones、np.block 等)，以及以元素為元素與 NumPy 中的線性代數運算，以及 3. 一個精心規劃的教學空間。
這些預期的結果將有助於新使用者完成文件、為文件提供清楚的樣式和格式、讓目前的教學課程內容更精簡且易於理解、將說明移至獨立章節，以及新的說明文件貢獻者不必建構完整的 Sphinx 說明文件，就能協助使用少量案例。我們希望繼續打造教學與學習社群，
新的說明文件貢獻者可以協助數百萬名使用者，輕鬆製作完整的 Sphinx 說明文件。我們希望繼續打造教學與學習社群，這份提案的說明文件將模仿目前的開放原始碼文件，例如 Matpaintlib、Divio 等。新使用者和潛在協作者可以更輕鬆地在相關領域和軟體中運用 NumPy。
專案時程為 9 月 14 日至 11 月 30 日。第一步是將目前教學課程中的說明文件和內容區隔成教學課程、教學內容和說明內容。這項作業將在專案計畫的前五週完成，並分別用於《結案 1》及 2 項網站和教學課程。下方「建議文件」顯示的是這份提案機構。
建議文件：
i.Tutorials:
- 初學者的絕對基本概念 (移除安裝內容，可將 pandas 匯入/匯出替換成 numpy.loadtxt?)
- 「What is 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 文件季後，我提議的成果如下：
- 修訂說明文件網頁，清楚地將四個空間區隔開來：教學課程、教學、說明和參考資料
- 新教學課程：建立陣列 (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 日有 4 個空間已定義並建立連結的網頁中 將目前的教學課程移到適當的空間和版本文件 10/10 提交公關到 PR3，並提議變更 11/1 回應網站/建議修改內容，並修訂 PR3
結果 2：修改教學課程 交付日期 9/21 檢閱教學課程修訂版本排名 9/21 將目前的教學課程內容分離教學課程和說明空間 10/1 寫入等級 1：讀取/寫入陣列 10/10 將 PR 寫入 github 以便分離及修訂 10/20 撰寫 PR 第 1 級 PR 第 1 級 PR
建議的教學課程修訂版本排名 (可能依導師/社群變更)：
讀取/寫入陣列目前空白頁面
建立陣列 (np.zeros、np.ones、np.block 等)不存在：可幫助新使用者介紹常見的陣列建立/互動工具，並展示及示範
元素項和線性代數運算 (+、-、*、/ 和 +、-@、linalg.solve) 不存在：這對於 1 來說特別實用。Matlab 使用者和 2. 採用線性代數 (機器學習、線性迴歸等) 的使用者
結果 3：精選的教學空間 交付日期 外部連結(問題/範例)
製作教學範例 (候選：如何找出吉他字串的自然頻率 10/20)
製作教學範本，為 10/1 的新貢獻者建立教學範本 公關和取景 1 計畫成員，以建立教學範本 PR 和 Framing 可能的貢獻
預期重要性
這份 Google Summer of Document 提案將製作 NumPy 說明文件、填補網站上缺少的教學課程，並取得文件貢獻者的協助。身為機械工程教授，我計劃要藉由區隔文件的方式，讓學生能瀏覽文件，並輕鬆地找到入門教學課程和操作指南。詳盡的說明文件提供教學課程、操作說明、參考資料和說明，為潛在協作者提供結構化範例，協助他們建立新的資源。建議的文件是為新手和經驗豐富的使用者提供教育和溝通交流的管道，他們提議使用與康乃狄克州大學的學生共同撰寫建議，記錄這個具有教育性和溝通的想法。我們希望所有使用者都能找到實驗、學習和加入 NumPy 社群的空間。
參考資料
- NumPy.org 網站存取時間：2020 年 7 月。
- NumPy GitHub 存放區。
- 說明文件系統。Divio.com 存取日期：2020 年 7 月。
- Dewey, John。民主與教育。Gutenberg 計畫，2015 年 8 月。
- Dewey, John。任務：Certainty George Allen and Unwin Limited。2005 年 6 月。