學習撰寫 NumPy 教學#
圖片來源：Daniele Procida 的 Diátaxis 架構，採用 CC-BY-SA 4.0 授權。
您將會做什麼#
在範本的引導下，您將撰寫一個 NumPy 教學。
您將會學到什麼#
您將能夠製作遵循標準格式並反映良好教學實務的教學。
您將學習開啟 NumPy 教學的三個標準標題 — 您將會做什麼、 您將會學到什麼、和 您將需要什麼 — 以及底部的一些選用標題 — 自行練習、 在實務上、 延伸閱讀。
您將會知道是什麼讓您將會學到什麼與您將會做什麼不同。
您將能夠區分教學和操作指南。
您將學習不該在您將會學到什麼區段中放入哪些內容。
您將需要什麼#
這個範本。
您的目標讀者的樣貌。
就像學校會列出高階課程的先修科目一樣，您可以假設讀者已經知道一些事情（您必須列出這些事情，如下一點所述）。過度解釋會讓教學變得冗長且模糊重點。
但也請設身處地為讀者著想，並考慮在過程中需要解釋哪些內容。
「您需要的東西」是一個清單，包含：
使用者在開始之前，機器上必須安裝的套件。不要包含
numpy。您在上一點中假設讀者已經知道的內容。不要說
Python；熟悉 Python 迭代器就可以了。
非正式和熱情的語氣。想像您的讀者不是坐在觀眾席中，而是坐在您旁邊。
願意在**您需要的東西**的項目符號中使用不完整的句子。它們不需要以「您需要」開頭。
英文母語能力**並非**必要條件。其他人可以提供協助。
在水平線之後，開始您自己的標題#
您的教學步驟從這裡開始，使用您選擇的標題。在教學的結尾，您將放置另一條水平線，並返回標準標題。
標題包含動詞#
一般來說，標題中應包含動詞；因此使用**學習如何撰寫 NumPy 教學**而不是「NumPy 教學規則」。也請考慮在標題中加入動詞。
標題使用小寫#
第一個單字要大寫，之後只有通常需要大寫的單字才需要大寫（所以不是「標題使用小寫」）。
在「您將學到什麼」中該說些什麼#
避免抽象。「關於」是一個提示：不要寫「您將學習關於 NumPy I/O」，而是寫「您將學習如何將逗號分隔的文字檔讀入 NumPy 陣列」。
為什麼「您將做什麼」和「您將學到什麼」不同？#
**您將做什麼**通常是用一句話列出最終產品：「您將烤一個蛋糕。」 這讓終點很明確。**您將學到什麼**列出收穫，而且可能有很多：「您將學習如何遵循食譜。您將練習測量食材。您將學習如何判斷蛋糕何時可以出爐。」
避免題外話#
正如文件撰寫專家 Daniele Procida 所解釋的
不要解釋學習者為了完成教學不需要知道的任何事情。
由於教學步驟的選擇是為了清晰易懂，它們可能達不到生產級的標準。是的，您應該分享這一點，但不是在教學過程中，教學應該直接且肯定。《實際操作》部分是說明細節、例外情況、替代方案和類似注意事項的地方。
使用圖表和插圖#
圖表是一舉兩得；它們可以強化您的觀點，並使頁面更具吸引力。與英文能力一樣，藝術技能（或繪圖工具技能）並非必要條件。即使您只是掃描手繪插圖，也有人可以幫您潤飾。
標題下方的插圖，即使只是裝飾性的，也能讓您的頁面與眾不同。
盡可能使用真實的資料集#
讀者更容易被真實的案例吸引。請確保您擁有資料的使用權利。
教學和指南 – 相似但不同#
教學的讀者就像外地遊客，想感受一下這個地方。選擇任何一個目的地，並沿途解說景點。
與知道自己需要什麼的指南讀者不同，教學的讀者不知道自己不知道什麼。因此，雖然教學需要像您將會做什麼和您將會學到什麼這樣的標題，但這些標題永遠不會出現在指南中。
使用 Google 文件風格指南#
NumPy 文件遵循 Google 開發人員文件風格指南。除了提供重複出現問題的答案（例如「crossreference」或「cross-reference」的寫法），本指南還充滿了可以強化您的文件撰寫的建議。
筆記本必須完全可執行#
執行 所有 儲存格 應該執行檔案中所有儲存格到檔案底部。如果您要示範一個錯誤的表達式並想顯示追蹤資訊，請將該表達式註釋掉，並將追蹤資訊放在文字儲存格中。
（請注意，三個反引號不足以容納包含 <尖括號內的文字> 的追蹤資訊，尖括號必須替換為 < 和 >，如下面的文字儲存格 Markdown 所示。）
# 100/0
---------------------------------------------------------------------------
ZeroDivisionError: 除以零
自行練習#
用一條水平線結束教學部分。您現在可以自由選擇任何方向，但這裡有三個建議的章節。
在一個可選的 自行練習 章節中，您可以提供一個作業讓讀者練習他們的新技能。如果它是一個有答案的問題，請提供答案 – 也許可以用註腳的方式，以免破壞讀者的學習體驗。
實務上…#
您可以將您先前避免的詳細說明放在這個章節。
不要只說通常用另一種方式完成；要解釋為什麼。