本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- DIPY
- 技術撰稿人：
- Areesha Tariq
- 專案名稱：
- 高層級重組和以使用者為重心
- 專案長度：
- 標準長度 (3 個月)
Project description
我是軟體工程師，具備技術寫作專業知識。我在編寫高品質軟體文件、使用手冊、手冊和專案說明方面擁有超過 4 年的經驗。我住在巴基斯坦伊斯蘭馬巴德 (時區：UTC+5)。目前，我在 Outreachy 擔任實習生，這個職位會持續到 8 月 18 日。 我曾以 OpenELIS Global 組織的技術文件撰稿人身分，參加 Google 文件季活動。原始說明文件是法文，內容有限且過時，因此我建立了英文版的完整且更新的使用者說明文件。我於 2020 年 5 月至 8 月期間，在 Perl & Raku 機構的 Outreachy 計畫中獲選，擔任 Open Food Facts 伺服器的後端開發人員。除了後端開發作業外，這個實習計畫的主要任務之一，就是以 POD 格式為模組和函式建立文件。去年，我開始涉足開放原始碼的世界，參與了幾個開放原始碼專案，後來也參與了 Google 的「Docs 季節」活動。今年，我在 Outreachy 獲選為開放原始碼和免費軟體的多元性。我對 Git 非常熟悉，因為 Outreachy 專案託管在 GitHub 上，而且自 3 月起，我一直定期為 Open Food Facts 和 Mozilla Fenix 做出貢獻。我使用 Linux 超過 3 年，從那時起就一直使用終端機指令。
我使用的說明文件工具和語言包括 Sphinx、Read the docs 和 Markdown。我很喜歡這個想法，也想著手進行，因為我有相關經驗，而且很樂意運用自己的知識和技能為 DIPY 做出貢獻。我在數位影像處理、電腦視覺和機器學習領域擁有豐富的經驗。這有助於我進一步瞭解神經影像技術，並協助建立相關文件。我在醫療領域擁有豐富的經驗。我開發了一個醫療網站，專供醫師、患者、實驗室和救護車司機參考。我任職的系統是醫生、患者、護理師、實驗室助理和研究人員使用的另一個系統。這樣我就能製作更容易理解的文件。
我已查看 DIPY 的說明文件，並記下其中幾個缺陷。說明文件中有多個漏洞，我打算改善這些問題。說明文件目前的狀態： 說明文件缺乏特定結構和設計 使用者可能會覺得瀏覽說明文件很費時費力，尤其是新手 使用者可能會覺得很難從說明文件中取得資訊 說明文件的內容需要改善 我發現新手很難存取使用者手冊和開發人員手冊。說明文件需要重新調整，讓使用者能輕鬆存取所需資訊 說明文件缺乏一致性
我打算採取以下行動：
定義說明文件的特定結構和範本 重新調整說明文件內容，方便使用者找到必要資訊 製作藍圖或工作項目清單，以進一步與社群互動 定義使用手冊和開發人員指南範本 定義範本，用於提供指南 重新編寫、重構及更新使用者指南、開發指南，並協助提供全新內容的說明文件 協助並激勵新使用者改善專案介面
使用手冊：
對於使用手冊，我會將重點放在使用簡單明瞭的用語，協助使用者瞭解即使是最複雜的系統。為提升使用者體驗，我們會避免新使用者可能知道的術語、縮寫和其他內部資訊。我也會將重點放在使用影像內容，像是圖片、註解螢幕截圖、圖像和影片，幫助使用者快速瞭解系統的運作方式。良好的說明文件需要有層級分明的標題和副標題，讓使用者瞭解各個部分會顯示哪些內容。該階層應遵循邏輯流程，協助使用者以最實用的方式學習如何使用系統。這項專案的主要目標之一，就是建立無障礙內容。所有文件和指南都會採用一致的樣式。請務必在多份文件中使用一致的字型和互補色，我會確保使用者可以存取機構的更多資源，協助他們順利運用系統。
開發人員指南：
開發人員指南提供豐富的指引和參考資料，協助開發人員為 DIPY 的原始碼做出貢獻。這項工具會嘗試列出您可用的各種選項，讓您根據想要達成的目標使用適當的方法。開發指南需要重新調整及重組。我會重寫開發人員指南的內容。開發人員可以輕鬆存取建構依附元件、貢獻指南、樣式指南、程式設計慣例、說明文件指南、安裝開發環境、偵錯、測試指南和相關內容。當熱心的新貢獻者急著為您的專案做出第一個開源貢獻時，他們會依循貢獻指南作為指引。因此，規範應易於閱讀、詳盡且友善。貢獻指南是實用的文件，可說明使用者如何為開放原始碼專案做出貢獻。無論是提交修正程式、回報錯誤、成為維護者、討論程式目前狀態，還是提出新功能，使用者都應能輕鬆且清楚地參與專案。
TEMPLATE
這是可用於貢獻內容指南的其中一個範本。您可以根據文件需求修改內容，並新增或移除章節。
為 DIPY 貢獻
- 歡迎訊息
TOC
行為準則
- 我們的標準
- 舉例說明有助於營造正面環境的行為
- 參與者不當行為示例
- 我們的責任
- 專案維護者的責任
- 範圍
行為準則的範圍
我需要知道哪些資訊才能提供協助？
如果您想協助我們使用專案的程式碼貢獻 [插入專案使用的程式設計語言、架構或工具清單]。如果您還不想貢獻程式碼，也沒關係！您也可以查看說明文件問題 [連結至 Issue Tracker 上的說明文件標籤] 或我們遇到的設計問題 [連結至 Issue Tracker 上的設計標籤，如果您的專案追蹤設計問題]。如果您有意提供程式碼，並想進一步瞭解我們使用的技術，請參閱下列清單。列出資源 (教學課程、影片、書籍) 的項目符號清單，讓新貢獻者可以瞭解使用者必須具備哪些知識，才能為專案做出貢獻。
設定開發環境
在本節中，我會新增需要安裝的安裝程序和依附元件。安裝 $project 執行：安裝專案
- 原始碼：github.com/$project/$project
- Issue Tracker：github.com/$project/$project/issues
如何貢獻
如何回報錯誤
- 提交錯誤報告前
- 如何提交 (良好的) 錯誤報告？
如何提交變更內容
- 提取要求通訊協定
- 該團隊的回覆
- 回應速度
如何要求改善
- 提交強化建議前的注意事項
- 如何提交 (良好) 改善建議？
首次貢獻程式碼
- 新手問題
- 需要協助的問題 #### 提取要求
- 建立提取要求的程序
- 確認所有狀態檢查都通過。
如果狀態檢查失敗，該怎麼辦？
- 編寫測試
- 測試涵蓋率
風格指南
- Git 修訂版本訊息
- 標準樣式
支援
如果您遇到問題，請告訴我們。如需協助，請透過我們的電子郵件清單 (project@google-groups.com)、IRC 即時通訊或 [列出專案使用的任何其他通訊平台] 提出問題。
授權
本節將說明專案的授權。
時間承諾和溝通：
我會每週投入 45 小時以上，但如果發生任何意外，我會在週末補上這些時間。在社群連結期間，我會與導師討論溝通方式，並敲定每週會議的時間、方式和時間。我會持續向導師更新工作進度，並透過電子郵件與導師分享工作詳細資料。我偏好使用 TeamViewer，因為這十分容易使用，例如分享螢幕畫面等。