本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- SciPy
- 技術撰稿人：
- mkg33
- 專案名稱：
- 以使用者為導向的說明文件和徹底的重整
- 專案長度：
- 標準長度 (3 個月)
Project description
動機：
我打算重新整理現有的說明文件，讓有不同需求的使用者都能輕鬆存取。不言可喻，研究人員最有可能對進階和細微的功能感興趣，而沒有相關專業知識的使用者則會喜歡逐步指南和圖表。
我之所以有興趣參與這個專案，是基於個人和專業原因：首先，我希望為 SciPy 做出重大貢獻，因為我自己的研究從中獲益良多；其次，我經常在其他軟體中遇到不完整 (或缺乏) 的說明文件，因此一直在思考，如果提供完整指南，使用者學習如何使用程式碼的速度會快多少 (如果全部提供的話)。
目標：
我希望改善現有的 SciPy 說明文件，包括內容和圖像。我解決這個問題的方法最重要的特點，就是部署並分析使用者問卷調查，也就是在線上進行簡短的問卷調查，讓各種使用者都能表達他們對文件的需求。我深信，他們的意見應該是創作靈感的源頭 (還有什麼方法可以製作更容易瀏覽的文件？)。
就專案本身的實現方式而言，第一階段將涉及設計和分析使用者問卷調查，以及解決我目前在文件中發現的幾個文體問題。例如：缺乏一致性 (例如：與二維陣列一併出現 2D 陣列)、經重寫的連續句子，或某些子頁面中缺少字母順序。第二階段將著重於推出含有相關主題超連結的圖像指南 (根據調查結果和其他社群要求)。長期來說，我希望能針對不同類型的使用者，提供令人滿意的說明文件。此外，我會盡量讓教學課程在語言和結構上更一致。最後，我希望能根據目前社群的需求撰寫新的教學課程。
使用者問卷調查：
基於使用者問卷調查，我建議基於幾項原因使用 Google 表單。首先，Google 表單是免費的，而且提供無限的功能 (在受訪者人數、問題數量等方面)，並且有吸引人的視覺表單、最實用的問卷選項 (例如可自訂的線性刻度、核取方塊和選擇題)，最重要的是，您可以輕鬆匯出結果，用於統計分析。根據線上研究，至少目前來說，Google 表單似乎是進行問卷調查的最佳免費工具。另外，在 Google 執行的計畫中使用 Google 產品，也是不錯的做法。
我已建立初步問卷調查，其中包含範例問題 (可前往 https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform 查看)。最終版本中合理的問題數量應介於 10 到 15 之間。為了取得具體結果，建議我們主要使用選擇題、線性量表和一些複選框。不過，線性比例不應類似完整的光譜 (這只會造成混淆，且結果可能會受到高離散度的影響)。最多只能有兩個開放式問題，否則結果會非常分散，完全沒有幫助。我認為，即使回覆數量龐大，也不會造成問題，因為您可以輕鬆匯出資料，並使用統計軟體自動分析。假設回應的數量非常高，分析開放式問題可能很耗時，但我認為不會讓人不知所措。畢竟一般使用者不太可能撰寫關於文件狀態的文章。在最糟糕的情況下，您可以只儲存部分答案，供日後分析之用。
圖形指南：
我認為圖像指南 (用於導覽工具) 的理念是建立在一個普遍的假設上，即 (大多數) 人更擅長處理簡單的視覺結構，而非純文字資訊。此外，以主題為導向的圖表，其中有線條連結相似的興趣主題，無疑是對經驗較少的使用者 (以及其他使用者) 而言極具價值的資產。
關於實作細節，建議使用 TikZ 套件。首先，這項工具功能強大，似乎不會很快淘汰。它也提供高品質的輸出內容、非常完善的說明文件，而且是 TeX StackExchange 和其他主流論壇的常見主題。最重要的是，由於 TikZ 檔案 (更精確地說有許多超連結) 和 HTML 說明文件的整合，由於各種套件及修正方法在 HTML 中嵌入 TikZ 圖片 (例如 TeX4ht)，並不會產生重大問題。
至於 SciPy 指南日後的維護問題，只要使用 Overleaf (可促進協作，並提供即時預覽功能) 和我提供的預先定義範本，就能輕鬆解決。基本上，圖形指南之間的差異不大。結構、調色盤和形狀或多或少都會保持不變，因此後續重新調整形狀和進一步自訂都不會有問題。
(請參閱共用 GSoD 資料夾中的完整提案版本)。