本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- MatGraphlib
- 技術撰稿人：
- jeromev
- 專案名稱：
- 開發 Matplotlib 輸入路徑
- 專案長度：
- 標準長度 (3 個月)
Project description
簡介
Matticklib 今年的 Google 文件季專案建議包含製作內容，向新使用者介紹 MatDrawlib。針對開發 Matplotlib 輸入路徑，我建議採用與現有說明文件不同的方法。我是新進的技術作家，但我的背景是教育和教育相關領域。技術文件寫作和教育方面的技能與眾不同，而且重點在於製作同理心的內容，並讓使用者透過提供的資源完成工作。
在此情況下，MatShapelib 說明文件會較有助於吸引新使用者的目光，將有利於提升。目前的大部分素材都包含隨機資料和未標示的視覺效果。這些方法非常適合快速顯示 Matplotlib 的圖像和功能。不過，對於使用 Matplotlib 的新手而言，要將資料轉換為圖表，就會遇到困難。
解說式方法中的背景資訊是解決這個障礙的解決方案。我們將以實際範例的角度編寫程序，藉此說明我們瞭解使用者的工作環境。這有助於改善說明文件與使用者之間的關係，讓使用者能達成目標或完成工作。
使用者有一致的衍生用途，例如鞋子公司的數據科學家必須向團隊呈現顧客資料，以說明一段時間內的購物趨勢。在這種情況下，使用者必須學習如何瀏覽 Matplotlib，並善用程式庫中的工具來完成手邊的工作。
如果新增補充說明文件的背景資訊，新使用者就能更容易辨識主題。使用者衍生用途與說明文件平行。我希望能實現開發人員主管 Tom Caswell 在 2017 年接受訪問時所提到的願景：「讓能夠實際撰寫內容且能同理使用者感受的人，撰寫一本 200 頁的『Matplotlib 入門』書籍，並將其做為文件的主要入口。」
說明性寫作替代做法
目前的說明文件將介紹 MatDrawlib 的功能，也就是使用者可對程式庫進行的操作。舉例來說，教學課程通常會遵循不影響基礎方法的模式。
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
在程式設計說明文件和支援服務中，我們通常會建議使用者自行執行程式碼，瞭解發生的情況。雖然程式設計思維可讓使用者更瞭解這個主題，但轉換作業的學習曲線幾乎沒有任何輔助內容。由於相關文件有限，因此這項工作可能會非常困難。
提供更多圖表、圖片或其他圖像，有助於創造新的學習機會。以下結構也可做為新內容的範本。此外，加入非文字圖片或圖形的目的，是為了利用說明文字和提示標記等功能。有時圖片會難以瀏覽，因為沒有指示程式碼如何或在何處轉換為執行的輸出內容。我認為影片缺少強烈的視覺元素，無法讓觀眾更深入瞭解主題。
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
這種替代做法對說明文件使用存放區寫入具有極大的潛能。使用者看到各種轉換概念後，就能更清楚瞭解將資料轉換為可視化圖表的基礎策略。這項知識可協助使用者發揮創意，並善用功能，例如根據實際用途提供的範例。
隨著 Matplotlib 的知名度提升，這個程式庫的聲譽也因其一貫的易用性和易用性而備受肯定。這些特性借助了它們所表現出的模式和常見策略，不僅是在程式碼內，也出現在說明文件中。如果 Matchartlib 的使用者在設計程式時很容易上手且符合標準，因為他們顯然正在增加使用率和擴充的資源，那麼這或許也是技術文件製作過程的一環。
使用者遇到問題時，通常會透過搜尋功能解決問題。請不要讓使用者依賴搜尋功能來瀏覽文件，而是讓他們在文件中自行建立課程，這樣效果會更好。在這種情況下，使用者會搜尋問題的解決方案，然後在遇到其他問題或需要更多資訊時，使用內嵌的完整連結。
這會涉及組織系統中自下而上的架構。對於 Matplotlib 中的每個主題，連結主題相似性和資訊主題的豐富網路有助於建立健全的網路。透過這個網路，使用者在瀏覽主題並探索更多與該主題相關的資訊時，更有可能繼續使用說明文件。
障礙物
對於這類全面且詳細的專案，總是會遇到挑戰。我剛進入這個產業，擔任技術作家，因此不太熟悉使用 Sphinx 和 ReST 撰寫文件。介紹 Mattillib 和 Git 領域的新手。處理這四個系統，並熟悉如何運用這些系統進行協作和研究，需要花費一段時間。我需要在社群凝聚階段和更早的時間委派時間，以便為入門級路徑奠定必要的基礎。在此期間，如果概念和基礎知識方面的問題，我必須向社群尋求進一步協助。
跨時區和線上平台協調合作也需要調整。業界人士會使用各種通訊管道，因此我必須確保自己在所有管道上都很容易取得聯絡。我會清楚說明優先處理的不同期待。雖然我只是在進入這個產業，才剛開始承擔這類工作，但我也投入了大量心力，讓他們抱持負責任的態度，樂於接受意見回饋與批評。我認為這些特質無論在哪個領域都很有價值。
此外，增加可用性測試是說明文件的一部分，我認為這對 Matplotlib 的輸入路徑有幫助。針對內容的可用性進行問卷調查，目的是提供使用者設定檔，也就是人物角色。使用者體驗、所屬產業和疑難排解記錄等資訊，都是很寶貴的資訊。這些元素構成程序背後的用語。當寫作符合讀者的程度時，內容不僅僅像教學內容一樣成熟，
要持續進行可用性測試，通常會遇到許多困難。在內容開發期間，我們經常只會進行單一測試 (如果有測試的話)，定期進行可用性測試，有助於推動內容敘述。我希望能與 Matplotlib 社群合作，設定時間表或定期進行可用性測試。
結論
我在閒暇時間曾使用過 Python 和 Mat 然後點選 lib。過去幾個月來，我透過現有說明文件和好奇心，自學了許多知識。我當時也看了一些影片，並向幾位導師請教。我在打造自己感興趣的程式設計課程時，還是能學到許多知識，甚至還有更多進步空間。
在看到 Matplotlib 和社群對 GSoD 的想法後，我認為這將是一次絕佳的成長經驗，讓我有機會提升技術寫作技巧，並從幕後人員身上學到更多知識。我認為這項 Matplotlib 專案很有意義，也是我熱衷的理念。
在修訂使用手冊時，我這個技術寫作者的目標是協助使用者完成所需工作，同時不受可用功能的數量所淹沒。我認為最佳的文件會持續發展，並適應使用者需求，讓任何使用者都能找到適合自己的解決方案。