本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- Wikimedia Foundation
- 技術文件撰寫者：
- Pavithra Eswaramoorthy
- 專案名稱：
- 改善 Wikimedia 技術紀錄片和影片攝影師的說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
1. 關於我
我在幾個月前就採用開放原始碼軟體，結果幾乎馬上就感到不堪負荷。我一直在努力完成繁瑣專案，希望能瞭解 Google Summer of Code 和 Outreachy 等開放原始碼計畫。「Google 文件季」的系列內容很有趣，而 Wikimedia Foundation 的專案構想獲得了我的好奇心，所以我開始進一步研究。
到目前為止，我的旅程一直相當令人振奮也令人感到困惑，包括「等等，什麼？」、「我知道了！」和「我該在上面留言嗎？」。 Wikimedia 社群在每個環節都給予了支持。從編輯頁面到建立額外資訊，我每天都學到新知。
一如預期，應用程式程序是以我的閘道組成開放原始碼社群。本提案以我身為新手的經歷為參考依據。
2. 專案
2.1. 描繪外框
這項專案旨在改善相關說明文件，協助 Wikimedia 網站撰寫技術文件撰寫人員和潛在影片攝影師。一套成熟的技術說明文件指南有助於改善整體文件內容，而參考有關建立螢幕側錄的參考資源，則可有效示範軟體功能。你可以針對這些領域的現有說明文件進行延伸，進一步支援新手和經驗豐富的貢獻者。並採用漸進式方法，開發這個內含實用資源的網路。
2.2. 交付項目
T197006 [https://phabricator.wikimedia.org/T197006] - 改善 Wikimedia 的文件人員的說明文件：
- 在說明文件/樣式指南中新增提示和範例。[https://www.mediawiki.org/wiki/Documentation/Style_guide]
- 在技術說明文件範本和建議中，針對特定類型新增 MediaWiki 專屬資訊：使用手冊、操作說明、快速入門指南、版本資訊和 README。[https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
- 測試及改善技術文件優先順序的規範。[https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
- 為不同類型的說明文件設計內容集合策略。
- 為 MediaWiki 的說明文件設計溝通和協作策略。
- 建立一份檢查清單，供撰寫者在發布文件前審閱。
- 展開新技術文件撰寫者的說明文件結構。[https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
- 收錄適合黑客鬆的技術說明文件工作清單。[https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
- 建立技術文件撰寫中心，藉此提供實用資源。
改善 MediaWiki 視訊攝影人員的說明文件：
- 製作一般螢幕側錄的快速使用指南。
- 設計 MediaWiki 專用螢幕側錄範本，以便取得逐步操作說明和教學課程內容。
T214522 [https://phabricator.wikimedia.org/T214522]- 製作「Phabricator 簡介」螢幕側錄。
2.3. 伸展目標
- 再次檢查內容並更新 WikiProject 螢幕側錄說明文件。(https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)
3. 導師
Zulip 將是與導師的主要溝通方式。將使用 Wikimedia 的 IRC 頻道和電子郵件與社群進行討論。 有關特定任務的討論會在「Phabricator」工作的註解部分中進行。
4. 討論
這項專案大致分為兩個階段：
(i) 改善 Wikimedia 技術文件撰寫者的現有資源。
(ii) 為有需要的影片攝影師製作實用範本。
(i) 改善 Wikimedia 技術文件撰寫者的現有資源。
過去，為了改善 MediaWiki 說明文件，採取了幾項計畫，以不同程度的成功程度做為改善依據。例如：
- https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
- https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
- https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
- https://www.mediawiki.org/wiki/User:Waldir/Docs
透過這些努力，我們能瞭解為技術文件撰寫者提供更完善的資源，就能直接影響他們產生的文件。
以下為 2018 年實習生 Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/ 2018 年實習機會報告的摘錄內容：
「MediaWiki 的樣式指南其實並不完美，尤其是仰賴外部參考資料，但沒有突顯出最佳做法的做法。不過，這個問題不僅僅出現在 MediaWiki 之外，也會出現在其他說明文件中 (例如 Translation 最佳做法)。寫作者最終若缺乏豐富可靠的資源，便無法建立目標觀眾群和適當的寫作風格。使用者 (尤其是新使用者) 在瞭解新概念和處理程序時可能會遇到問題。」
T197006 [https://phabricator.wikimedia.org/T197006] 也針對技術寫作文件，說明瞭需要改善的部分。明確地說，Documentation/Style_guide 是著手開始的地方。
一旦我們有更完善的樣式指南，下一組文件就會為技術文件撰寫者完成不同的技術撰寫階段。文件內容必須容易理解，同時請提供所有必要資訊，方便撰寫者參考。
預備階段可能最重要，因為它是建立文件的基礎。為支援技術撰寫專員在這個階段，我們開發參考文件時，一併說明如何有效收集相關資訊，以及使用範本建構這類資訊的訣竅。
接著進入寫作階段。為作者提供適合自動提高標準品質的好作品範例。此外，我們也會建立檢查清單，列出每份文件必須遵循的基本條件，這有助於撰寫者在發布文件前先行檢查。
即使擁有這些文件，新的技術文件撰寫專員仍需要額外的協助，因此我們需要給予他們額外的協助。我們準備了新技術文件撰寫專員專用的指南，內容會根據難度等級整理出適合黑客鬆的工作清單。
最後，為瞭解管理和維護說明文件的程序，「技術文件優先順序」經過測試和改善。
在這個階段結束時，我們將會建立技術寫指南、資源、範例、建議和範本的中心，以便支援這份說明文件樣式指南。
(ii) 為有需要的影片攝影師製作實用範本。
「學習圖像方面的最難學習方法之一，就是閱讀純文字。再舉一個例子，假設手動操作的軟體版本錯誤，由於我們缺少平常會使用的所有提示，如果應用程式的選單和用語有所變動，就無法重建一系列動作。
或許最好的學習方式是，一位專家在旁坐著。螢幕側錄位於靜態圖像之間，可讓專家在手邊關閉。我們透過親切的語音示範移動式示範，還能在畫面和動畫中加入文字註解。相較於專家，螢幕側錄的一大優勢就是每天每小時都可以重播一次。
我們還能為螢幕側錄新增翻譯字幕，方便非母語人士觀看，或是用其他語言替換音軌。」
在上方的「螢幕側錄手冊」程式碼片段 [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] 中，Ian Ozsvald 說明瞭螢幕側錄的重要性。這對於包含 MediaWiki 開發環境、編寫擴充功能以及使用 Gerrit 等主題的教學課程而言特別實用。
就像文件範本一樣，螢幕側錄也能使用標準範本來推廣統一，有助於提升檢視者的體驗。也會為潛在的影片攝影師提供入門架構。因此，我們除了提供簡要的使用者指南，還設計了用來製作簡介和教學影片的範本。文件會指出要涵蓋的概念深度，以及一些 MediaWiki 的螢幕側錄構想。
如要測試上述範本並準備延展目標，最好的方法就是使用相關工具和範本建立螢幕側錄。因此，我們製作了「Phabricator 簡介」螢幕側錄，內容涵蓋「Phabricator」的基本概念。這個過程也會醒目顯示需要討論的部分。
最後，Wikimedia 影片攝影師 (WikiProject 螢幕側錄) 的主要參考來源已經過審查及更新。
5. 暫定時間軸
社區凝聚期間 (8 月 1 日至 9 月 1 日)
- 與我的導師詳細分析專案。
討論主題：
- 審查工作的頻率。
- 共用時間表，決定每週/每日工作流程。
- 可用的工具和資源。
- 每兩週和每日專案報表。
在 Phabricator 中建立必要工作和子工作。
在文件開發階段，建立草稿來補強個人承諾。
第 1 週 (9 月 2 日至 9 月 8 日)
改善 Documentation/Style_guide：
- 改變主要目標，說明 MediaWiki 的最佳做法和標準。
- 提供優質作品示例，提高相關網頁的能見度。
撰寫給新技術文件撰寫者的指南：
- 展開說明文件結構。
第 2 週 (9 月 9 日至 15 日)
決定技術文件的優先順序：
- 評估說明文件，尋找良好的工作說明和優先順序範例。
- 研究趨勢並記下常見難題。
- 運用這份資訊和範例來記錄優先順序標準。
第 3 週 (9 月 16 日至 9 月 22 日)
為技術文件撰寫者建立下列其他文件：
- 這份檢查清單可在發布前檢查技術說明文件。
- 有效收集不同文件類型內容的方法。
第 4 週 (9 月 23 日至 9 月 29 日)
將常見 MediaWiki 類型的書寫資訊新增至技術說明文件範本和建議中：
- 記錄 MediaWiki 的最佳做法，包括撰寫使用手冊、快速入門指南、README、版本資訊和使用方法。
新增指示，提陞技術溝通的成熟度。[https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]
第 5 週 (9 月 30 日至 10 月 6 日)
改善新手上路文件：
- 更新網頁：黑客鬆的技術說明文件工作。(待辦事項：請在專案期間全程將合適的工作項目加入這個頁面)
打造技術文件撰寫中心
- 建立到達網頁，並在其中提供實用網頁和資源的連結。
- 在新網頁和現有網頁中加入必要連結，以便瀏覽。
第 6 週 (10 月 7 日至 13 日)
建立下列文件，瞭解如何製作 MediaWiki 影片：
- 《建立一般螢幕側錄》並指向螢幕側錄專案的快速使用指南。
- 範本：軟體/工具的逐步操作說明；開發新工具的教學課程。
為 MediaWiki 建立螢幕側錄提案清單。
第 7 週 (10 月 14 日至 20 日)
製作「Phabricator 簡介」影片：
- 使用範本 (上週建立) 擬定指令碼。
- 評估範本效率，並視需要加以改善。
- 取得意見回饋並完成草稿。
第 8 週 (10 月 21 日至 10 月 27 日)
發布「Phabricator 簡介」影片：
- 選取並安裝軟體。
- 設定環境並建立螢幕側錄。
- 記下遇到的問題以及解決方法。
第 9 週 (10 月 28 日至 11 月 3 日)
改善螢幕側錄專案說明文件：
- 請檢查結構，並討論是否需要調整。
- 查看提及的軟體。
- 研究並更新軟體清單。
第 10 週 (11 月 4 日至 11 月 10 日)
繼續改善螢幕側錄專案說明文件：
- 評估及改善教學課程和指令碼。
- 查看螢幕側錄圖庫。
第 11 週 (11 月 11 日至 17 日)
完成螢幕側錄專案說明文件的工作：
- 尋找新影片並新增至媒體庫。
- 進行必要的結構變更。
第 12 週 (18 月 18 日至 11 月 24 日)
處理任何待處理的工作。
編寫最終報表：
- 查看每兩週/每日報表，收集必要資訊。
- 規劃報表結構並撰寫草稿。
- 根據導師的意見回饋修改草稿，並完成草稿。
第 13 週 (11 月 25 日至 11 月 29 日)
- 提交最終報告和導師評估。
6. 進度追蹤
每日進度更新會透過 Zulip 通知導師。Wikimedia 社群可透過 Phabricator 或每兩週的專案報告追蹤我的進度。
7. 其他承諾使用合約
我是全職大學生，我的學術秋季學期與 Google 文件季度的時間軸有所重疊。因此，我的承諾包含大學考試。
第一項內部考試：8 月 18 日至 24 日
第二次內部考試：9 月 29 日至 10 月 6 日
學期測驗：11 月 11 日至 30 日
多虧了今年 10 月 12 日至 15 日，我打算在 10 月 12 日至 15 日參加第一屆公開會議 PyCon India，我認為這是與新使用者互動交流的大好機會，雙方可以展開對話。
為了管理這些承諾使用合約，暫定時間軸在對應幾週包含的權重較少工作。我打算在秋季結束前完成 20 份核心抵免額，才有足夠時間開發文件。(一般學生每學期平均完成 25 次學分)