本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- SciPy
- 技術文件撰寫者：
- mkg33
- 專案名稱：
- 以使用者為核心的說明文件並全面重組
- 專案長度：
- 標準長度 (3 個月)
Project description
動機：
我打算重構現有說明文件，讓具有不同需求的使用者能輕鬆存取。由此可知，研究人員最有可能對進階和細微功能感興趣，而沒有專業知識的使用者卻喜歡逐步指南和圖表。
我是為了個人和專業而推動這項專案：首先，我想對 SciPy 做出重大貢獻，畢竟我的研究受到許多幫助，而且我在其他軟體中經常遇到 (或缺乏) 說明文件不足，而且總是想知道使用者可透過提供完整指南，瞭解如何使用這些文件來學習使用速度有多快。
目標：
我想改善現有的 SciPy 說明文件與圖像內容。解決這個問題時，我最重視的一點是使用者問卷調查的部署與分析作業，也就是建立一份簡短的線上問卷調查，讓眾多使用者表達他們對說明文件的需求。我堅信使用者意見應從靈感來源 (我該如何建立更容易理解的文件？)。
至於專案本身的具體可行性，第一階段將會設計及分析使用者問卷調查，並解決我在目前的課題中發現的幾項風格問題。例如，缺乏一致性 (例如與二維陣列一起發生的 2 維陣列)、需要重寫的捲積句子，或者某些子頁面缺少字母順序。第二階段的重點是介紹圖形指南，其中包含相關主題的超連結 (根據問卷調查結果和其他來源要求)。長期下來，我想為各類使用者提供了符合需求的說明文件。此外，我會嘗試算繪教學課程內容，以更一致的語言風格和結構。最後，我的目標是根據目前的社群需求撰寫新的教學課程。
使用者問卷調查：
根據使用者問卷調查，我提議使用 Google 表單的原因有幾個。首先，Google 表單完全免費，且提供不限數量的功能 (作答者、問題等) 具有吸引力和最實用的問卷調查選項 (例如自訂線性尺度、核取方塊和單選題)，最重要的是，您可以輕鬆地將結果匯出為統計分析。根據線上研究資料，Google 表單目前至少是最適合進行問卷調查的免費工具。說真的，在 Google 推出的計畫中使用 Google 產品時，最好的方式稍加留意。
我製作了包含範例問題的初步問卷調查 (網址為 https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform)。最終版本中的問題數量應介於十到十五之間。為獲得具體結果，建議您優先使用選擇題、線性比例和幾個核取方塊。不過，線性尺度不應類似於整個頻譜，但這種比例只會造成混淆，且結果很可能受到高焦距的影響。開放式問題最多沒有兩個，否則結果會過於分散，完全不有幫助。我認為即使數量非常多的回應也不會發生問題，因為資料可輕鬆利用統計軟體自動匯出和分析。假設回應的數量確實非常高，分析開放式問題可能相當耗時，但我相信不會令人眼花撩亂。畢竟，一般使用者不太可能撰寫關於說明文件狀態的論文。最糟的情況是，部分答案可以輕鬆儲存供日後分析之用。
圖形指南：
我對圖形指南 (原本是做為導覽工具) 的願景是根據一項熱門的考量，其中 (大部分) 比較適合處理簡單明瞭的視覺結構，而非單純使用文字資訊。此外，以主題為導向的圖表，能連接類似主題的線路，這無疑是對經驗不足的使用者而言相當實用 (不僅是寶貴資源)。
至於實作細節，建議使用 TikZ 套件。首先最重要的一點，這是一項強大的工具，不太有可能即將遭到淘汰。同時也提供高品質的輸出內容、提供可靠的說明文件，而且是 TeX StackExchange 和其他主流論壇上的常見主題。最重要的是，整合 TikZ 檔案 (更確切地說，裡面有許多超連結) 與 HTML 說明文件中似乎沒有重大問題，因為存在多種套件，而且也修正了將 TikZ 圖片嵌入 HTML (例如 TeX4ht)。
我們可以輕鬆解決 SciPy 指南日後維護的問題，您可以使用「Overleaf」(促進協同合作，並提供即時預覽) 和我提供的預先定義範本來解決。基本上，圖形指南通常不會有太大差異。結構、色彩調色盤和形狀多半無法改變，因此後續重新塑形和進一步自訂並非問題。
(如要查看完整版提案，請前往共用的 GSoD 資料夾)。