建立專案報表

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

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

正在提交專案報告

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

專案報告包含的資訊

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

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

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

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

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

專案報告的要求

請謹記下列規定:

  • 連結內容必須易於識別您在使用文件季節完成的工作,也就是您所做的變更或編寫的新文件。
  • 工作應保持在穩定的位置。提交後即無法變更網址。
  • 其他人應能使用 (或參照) 連結目標的內容建立您的工作。

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

舉例說明如何描述作品

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

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

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

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

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

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

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

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

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

不當描述作品說明

請避免以下行為:

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

導師課程

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

請檢查下列事項:

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

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