建立專案報表

注意： 本說明文件適用於 2019 年文件季計畫。目前的計畫說明文件。

目前階段：
「2019 年文件季別」計畫已於 2020 年 3 月 6 日結束。請參閱時間表。

本頁提供技術文件撰寫者的指南，說明完成今年文件季度後，該如何建立專案報表。

正在提交專案報告

專案敲定階段開啟後，您即可在技術文件撰寫者指南的專案最終部分中填寫一份表單，提交專案報告。

專案報告包含的資訊

本節說明您可以在專案報表中提供的資訊類型。專案報告表單會包含任意文字欄位和選擇題。

連結至你的作業

請提供您完成作品的說明連結。

此連結應指向一份文件，其中含有作業的簡短說明、合併至存放區的開放原始碼專案說明文件、專案目前狀態的摘要，以及挑戰與學習成果的清單。

連結會顯示在網站上發布的「文件季別」結果中。 已發布的結果會顯示您在程式期間完成的工作。已發布的結果也很適合用來補充參考資料，做為履歷的一部分。

請先與導師分享連結，並要求進行審查，然後再提交專案報告。

專案報告的要求

請謹記下列規定：

• 連結內容必須易於識別您在使用文件季節完成的工作，也就是您所做的變更或編寫的新文件。
• 工作應保持在穩定的位置。提交後即無法變更網址。

• 其他人應能使用 (或參照) 連結目標的內容建立您的工作。

  • 如果作業完全完成，其他人應能運用。
  • 如果研究成果未完全完成，您將會知道還剩下哪些部分。

舉例說明如何描述作品

您不必執行所有 (或任一) 操作，但只要按照以下步驟操作，就能滿足需求條件：

• 建立網誌文章或網頁或公開 GitHub 資料庫來說明您完成的工作，並連結至您所做的修訂和您所使用的存放區。如果專案仍有未完成的工作，請納入該工作的說明。你也可以分享精華片段或具挑戰性的內容

  這種做法能讓您輕鬆加入許多資訊，因此是最理想的做法。這項做法很有幫助，因為可以清楚呈現你所做的努力，也讓其他人更容易使用及理解你的貢獻。

• 如果使用 GitHub，且您的所有工作都涵蓋在單一提取要求中，您可以使用該連結。

  • 請務必提供詳細的提取要求說明。
  • 務必在說明中清楚註明任務適用於整季文件。
  • 如果提取要求在文件季節結束後需要執行更多工作，請務必確保文件修訂版本的最後一季中註明瞭這一點。
  • 這種提供專案報表的方法可將變更記錄、修訂版本清單和審查留言全部集中在一處。

• 如果 GitHub 存放區是用於旺季文件的單一用途，請新增包含工作詳細資料的 README 檔案。

• 在 Google 雲端硬碟中建立公開資料夾，並加入您建立的所有修補程式。

• 使用 Google 試算表建立公開試算表，並列出你所有的修訂版本。

• 公開 Issue Tracker 中的單一問題連結，針對你的工作和其他適當內容提供清楚的參照內容。這個問題應該會追蹤您完成的所有工作。確認問題列出了所有修訂項目，或能否以其他方式輕鬆找到修訂版本。

• 連結至變更內容的統合式或情境差異比較。請務必加入標題，並在其中加入技術寫作專案的名稱和您的姓名，方便其他人參考。

不當描述作品說明

請避免以下行為：

• 連結至含有整個專案原始碼或工作目錄的 tarball 或 ZIP 檔案。
• 專案主要來源存放區頂端的連結。舉例來說，如果您使用的是 CPython，則這個連結並不實用：https://github.com/python/cpython。
• 專案原始碼存放區副本的連結。這樣會難以看出您所做的變更，因為您的作品和其他人的作品混用。
• 連結至你的專案說明，在 Google 文件季度網站上。

導師課程

請協助技術撰寫者製作適當的專案報告。請務必先完成這個步驟，再建立您自己的技術文件撰寫人員的評估作業。

請檢查下列事項：

• 提交內容必須符合上述規定。
• 提交內容必須包含工作說明、滿足要求，以及特定決策的原因。

「文件季別」並不是技術撰寫者流失許多說明文件。這項工作對託管開放原始碼專案可能會有幫助。