本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- NumPy
- 技術撰稿人：
- cooperrc
- 專案名稱：
- NumPy 社群教育說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
簡介
NumPy 提供免費的開放原始碼軟體程式庫，可提供快速且精簡的陣列運算。這是 SciPy 堆疊中用於科學運算的基本套件 [1]。超過 37 萬個專案使用這個函式，可進行高效的陣列運算 [2]。NumPy 使用者會看到新的網站，其中包含應用程式和個案研究 [1]。新使用者在找到說明文件頁面後，會看到多個「從這裡開始」連結和入門教學課程，這些內容對初學者來說可能太多，例如 NumPy 基礎知識/位元交換。我在十年前就在畢業學校開始使用 NumPy。我發現自己會將網誌文章、講義和 StackExchange 解答拼湊在一起，以免需要閱讀 NumPy 說明文件。目前有超過 36 萬個 StackExchange 對話討論 NumPy。我認為其他使用者在 NumPy 也有類似的路徑。教育工具的基礎元素是溝通和社群 [4]。文件需要建立社群，反映專案目標。說明文件應為新使用者提供一致且清楚的指引。教學課程應提供新使用者易於遵循的步驟，並讓他們熟悉程式庫 [3]。這些說明文件應該歡迎新使用者加入 NumPy 社群。說明文件的結構、進度和作者，都必須營造出一個鼓勵探索和溝通的環境。這項提案將整理並填補現有 NumPy 說明文件中的空白，讓新使用者能瞭解相關知識並加入社群。
使用者透過測試和實驗獲得的知識 [4,5]。知識取決於測試和評估的方法。如果在教學內容中提供明確的目標和應用程式，就能讓使用者測試及評估新的想法和方法。社群成員可以建立知識庫，提升技能、知識和應用方式。說明區有兩大優點：首先，無論是新手還是老手，都必須設定一組明確的目標，才能進行測試並建立實驗。第二，潛在的文件撰寫者可透過這個空間，說明自己的目標、方法和解決方案。說明區域可滿足新使用者和潛在貢獻者的即時需求，讓他們更容易存取 NumPy 說明文件。目前的知識
John Dewey 曾說，學習的基礎是真實的體驗 [4]。NumPy 社群擁有大量實務經驗，可與其他使用者分享。教育產業奠基於社群和溝通方面的基礎。有條理分類的說明文件頁面，可讓新使用者輕鬆體驗 NumPy。它還會建立結構化範本，讓潛在貢獻者能分享 NumPy 的使用經驗。
軟體說明文件可分為四個大類別 [3]：教學課程空間、操作說明空間、說明空間和參考資料空間。NumPy 說明文件的教學課程區域包含多份文件，其中會將說明和操作說明內容混合在教學課程中。教學課程應以使用者教育為主，並以簡單易懂的步驟說明概念。說明區則提供更多以目標為導向的程序，讓使用者在實際應用中加以運用。說明空間會提供每個函式中詳細的說明字串。目前的教學課程和操作說明區域並未明確劃分，有時會進入說明和參考區域。我們為「完全初學者」提供了優質教學課程，而 Matlab 使用者則可參考「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) (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 Notebook。我會使用一些課程筆記/範例提交範例筆記本。我會建議學生在建立範本和構圖設計時，遵循版面配置和結構。這個學習成果提供真實的學習體驗，讓學生向更廣大的觀眾傳達概念和解決方案。這是學生參與 NumPy 社群並學習的絕佳機會。
結果 1：修訂網站 提交項目日期 分支存放區和使用 Sphinx 建構文件 9/21 建構網頁，並定義及連結四個空間 10/1 將目前的教學課程移至適當的空間，並建構文件 10/10 提交 PR 至 GitHub，並提出變更建議 11/1 回覆意見/建議並修訂 PR 持續進行，並與結果 2 一併完成 網站修訂 11/30
結果 2：修訂教學課程 提交日期 查看教學課程修訂排名 9/21 將目前的教學課程內容分隔為教學課程和說明空間 10/1 撰寫第 1 級：讀取/寫入陣列 10/10 提交 PR 至 GitHub，以便分隔和修訂 10/20 撰寫第 2 級：陣列建立 PR 11/15 撰寫第 3 級：元素和線性代數運算 PR 11/30
建議的教學課程修改排名 (視導師/社群而定)：
讀取/寫入陣列目前為空白頁面
建立陣列 (np.zeros、np.ones、np.block 等)不存在：可協助新使用者瞭解及示範常見的陣列建立/互動工具
元素和線性代數運算 (+,-,*,/ 和 +,-@,linalg.solve) 不存在：這對於 1 特別有幫助。Matlab 使用者和 2. 採用線性代數的使用者 (機器學習、線性迴歸等)
成果 3：精選的操作說明空間 提交日期 外部連結(問題/範例)
建立操作說明範例 (候選項目：如何找出吉他弦的自然頻率 10/20
為新貢獻者建立操作說明範本 10/1 進行中 教學範本 PR 與可能的貢獻內容
與其他貢獻者合作，建立招募康乃狄克大學學生和其他社群成員的操作說明筆記 7/1 狀態：已核准工作/學習計畫，並收到申請
預期重要性
這份 Google Summer of Docs 提案將製作 NumPy 說明文件 ，填寫網站上缺漏的教學課程，並吸引文件貢獻者。身為機械工程學教授，我打算將文件分門別類，讓學生能夠輕鬆瀏覽文件，並找到入門教學課程和實作操作說明手冊。分段說明文件 (教學課程、操作說明、參考資料和說明) 將為潛在貢獻者提供結構化範例，協助他們建立新資源。我們建議的文件可透過教育和溝通體驗，為新手和老手提供互利的使用體驗。與康乃狄克大學學生分享的教學示範教學提案，會將這個教學點子付諸實踐。我們希望所有使用者都能找到實驗、學習和加入 NumPy 社群的空間。
參考資料
- 存取日期：2020 年 7 月。
- NumPy GitHub 存放區。
- 說明文件系統。2020 年 7 月，Divio.com 存取了網站。
- Dewey, John. 民主與教育。Project Gutenberg，2015 年 8 月。
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 2005 年 6 月。