Wikimedia Foundation 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：

維基媒體基金會

技術撰稿人：

Pavithra Eswaramoorthy

專案名稱：

改善 Wikimedia 技術文件撰寫者和攝影師的說明文件

專案長度：

標準長度 (3 個月)

Project description

1. 個人簡介

幾個月前，我開始接觸開放原始碼軟體，但很快就發現其範圍無限，讓我感到不知所措。在努力完成無數專案的過程中，我瞭解到 Google 程式設計夏令營和 Outreachy 等開放原始碼計畫。「Google 文件」的季節似乎很有趣，而 Wikimedia Foundation 提出的專案構想勾起我的好奇心，於是我開始進一步探索。

我至今的學習歷程既令人興奮又令人困惑，經常會想「等等，什麼？」「啊，我懂了！」以及「我該對這個內容發表評論嗎？」。維基媒體社群在每個階段都給予我支持，從編輯網頁到建立擴充功能，我每天都能學到新知識。

正如預期，應用程式程序會做為我通往開放原始碼社群的閘道，這份提案的靈感來自於我自己初學時的經驗。

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 Screencast 說明文件。(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

透過這些努力，我們也瞭解到，為技術文件撰稿者提供的資源越完善，就越能直接影響他們產生的文件。

以下是 Outreachy 2018 年實習生 Anna e só 每兩週一次的報告摘要，網址為 https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/：

「MediaWiki 的樣式指南遠非完美，特別是因為它過度依賴外部參考資料，而未強調哪些做法是它認為的最佳做法。遺憾的是，這個問題並非只侷限於 MediaWiki，因為此問題會顯示在「Translation 最佳做法」等其他說明文件中。因此，作者無法取得可靠的資源來完成工作，導致難以建立目標對象和適當的寫作風格。使用者 (尤其是新手) 可能會遇到無法理解新概念和程序的問題。」

T197006 [https://phabricator.wikimedia.org/T197006] 也指出技術寫作文件中需要改善的特定部分。清楚地說，說明文件/Style_guide 就是起點。

取得更完善的格式指南後，下一系列的文件可規劃一系列文件，引導技術文件撰寫過程的不同階段。說明文件必須適合初學者使用，同時提供作者可參考的所有必要資訊。

準備階段可能是最重要的，因為這個階段會奠定文件的基礎。為了協助技術作家完成這個階段的工作，我們開發了參考文件，說明如何有效收集相關資訊，以及使用範本建構資訊的訣竅。

接著來談談寫作階段我們會提供優秀作品的範例，讓作者自動提高標準。此外，建立檢查清單時，每個文件都必須遵循一系列基本標準，協助撰寫者在發布文件前先行檢視文件。

即使有了這些文件，新的技術寫手還是需要額外的協助，而我們必須將其交給他們。我們已精進新技術作家指南，並根據難度挑選適合參與黑客松的任務清單。

最後，我們也測試並改善了「技術文件優先順序」文件，以便瞭解管理和維護說明文件的程序。

這個階段結束後，我們會建立一個技術寫作指南、資源、範例、建議和範本的中心，以支援說明文件樣式指南。

(ii) 為潛在的錄影師建立實用的範本。

「閱讀純文字是學習任何涉及圖像的內容最困難的方式之一。請想像，如果說明書參照的軟體版本有誤，會發生什麼情況。如果說明書只有文字，當應用程式中的選單和字詞變更時，我們通常會缺少所有常用的提示，因此無法重現一系列動作。

或許最好的學習方式，就是請專家坐在你身邊。螢幕錄影介於靜態圖片和專家指導之間，我們會透過親切的語氣實際操作示範介面，也可以在畫面和動畫中加入文字註解。螢幕錄影比專家更有優勢，因為你可以隨時隨地重播螢幕錄影。

我們也可以為螢幕錄影加上翻譯字幕，讓非母語人士觀看，或是將音軌替換為其他語言。」

在「The Screencasting Handbook」[https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] 的上述程式碼片段中，Ian Ozsvald 解釋了螢幕錄影的重要性。這類教學課程特別適合用於設定 MediaWiki 開發環境、編寫擴充功能、使用 Gerrit 等。

就像文件範本一樣，使用螢幕錄影的標準範本可提升一致性，進而改善觀眾的體驗。也為潛在的攝影師提供起步架構。因此，我們開發了快速使用者指南，並提供範本，方便您製作介紹和教學影片。文件中會提供指引，說明要涵蓋的概念深度，以及 MediaWiki 的幾個螢幕側錄構想。

如要測試上述範本並準備挑戰目標，最好的方法就是使用工具和範本製作螢幕錄影。因此，我們製作了「Phabricator 簡介」螢幕錄影，介紹 Phabricator 的使用方式。這個程序也會標示出需要討論的部分。

最後，我們也審查並更新了 Wikimedia 攝影師的參考資料來源：WikiProject Screencast。

5. 暫定時間表

社群連結期 (8 月 1 日至 9 月 1 日)

• 與導師詳細分析專案。

• 討論以下主題：

  • 工作應多久審查一次。
  • 分享時間表，並決定每週/每日的工作流程。
  • 可使用的工具和資源。
  • 每兩週和每日的專案報表。

• 在 Phabricator 中建立必要的工作和子工作。

• 建立草稿，以便在文件開發階段處理個人承諾。

第 1 週 (9 月 2 日至 8 日)

• 改善說明文件/Style_guide：

  • 將主要重點轉移到說明 MediaWiki 的最佳做法和標準。
  • 列出優質成果的範例，並增加相關網頁的能見度。

• 改善新技術文件撰寫人員的指南：

  • 展開文件結構。

第 2 週 (9 月 9 日至 15 日)

• 優先處理技術文件：

  • 評估文件工作板，找出良好工作說明和優先順序的範例。
  • 研究趨勢並記下常見的困難。
  • 使用這些資訊和範例記錄優先順序標準。

第 3 週 (9 月 16 日至 22 日)

• 為技術撰稿人建立下列額外文件：

  • 使用檢查清單，在發布前詳閱技術說明文件。
  • 有效收集不同說明文件類型的內容方式。

第 4 週 (9 月 23 日至 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 日 - 27 日)

• 發布「Phabricator 簡介」影片：

  • 選取並安裝軟體。
  • 設定環境並建立螢幕側錄。
  • 記下遇到的問題和解決方法。

第 9 週 (10 月 28 日 - 11 月 3 日)

• 改善螢幕錄影專案說明文件：

  • 檢查結構並討論是否需要進行變更。
  • 查看上述軟體。
  • 研究並更新軟體清單。

第 10 週 (11 月 4 日至 10 日)

• 持續改善螢幕側錄專案說明文件：

  • 評估並改善教學課程和指令碼。
  • 查看螢幕側錄圖片庫。

第 11 週 (11 月 11 日至 17 日)

• 完成螢幕側錄專案說明文件的工作：

  • 尋找並新增較新的影片至媒體庫。
  • 進行必要的結構變更。

第 12 週 (11 月 18 日至 24 日)

• 處理任何待處理的工作。

• 撰寫最終報告：

  • 參閱每兩週/每日報表並收集必要資訊。
  • 規劃報告結構並撰寫草稿。
  • 根據導師的意見回饋改善並擬定草稿。

第 13 週 (11 月 25 日至 29 日)

• 提交最終報告和導師評估。

6. 進度追蹤

我會透過 Zulip 將每日進度告知導師。Wikimedia 社群可以透過 Phabricator 或每兩週的專案報告追蹤我的進度。

7. 其他承諾

我是一名全職大學生，讀書學期也與「Google 文件」的「季節」時間軸重疊。因此，我的承諾包括大學考試。

第一次內部考試：8 月 18 日至 24 日

第二次內部考試：9 月 29 日至 10 月 6 日

末學期考試：11 月 11 日至 30 日

今年的會議地點很適合，因此我打算參加 10 月 12 日至 15 日舉行的首場公開會議：PyCon India。我認為這是認識新朋友並進行有意義對話的好機會。

為管理這些承諾，暫定時間表會在相應的幾週內納入較不重要的工作。我打算在秋季學期完成的核心學分不超過 20 個，以便有足夠的時間撰寫文件。(一般學生每學期平均修習 25 學分)