本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- Matchartlib
- 技術文件撰寫者：
- jeromev
- 專案名稱：
- 開發 Matchartlib 項目路徑
- 專案長度：
- 標準長度 (3 個月)
Project description
簡介
Matmaplib 為今年 Google 文件季度帶來的專案建議，內容涵蓋製作內容，協助新使用者瞭解 Mattulib。針對開發 Matchartlib 項目路徑，建議採取替代做法來取代現有說明文件。我是業界的新技術撰稿人，但我的背景位於教育和教育相鄰的領域。技術寫作和教育有強而有力的合作關係，那就是製作能展現同理心，並讓使用者透過提供的資源完成工作的內容。
在這種情況下，Mattulib 說明文件將能促進對新使用者的同理心。目前大部分的資料都是由隨機資料和未加上標籤的影像內容組成。很適合用來快速顯示 Mattulib 的影像和功能。不過，對於剛接觸 Mattulib 的使用者，將資料轉換為視覺化內容並不容易。
提供陰謀論的背景資訊是這個障礙的解決方案。透過以真實世界範例的角度寫出手術程序，我們即可示範使用者的工作環境。這樣可以提升說明文件與使用者之間的關聯，在達成工作的目標或期望方面提升表現。
使用者有一致的衍生目的。舉例來說，鞋子公司的數據資料學家必須向團隊提供客戶資料，以便呈現長期的購物趨勢。在此情況下，使用者必須瞭解如何瀏覽 Mattulib，並利用程式庫中的工具完成手邊工作。
如有額外的背景資訊來佐證說明文件，新使用者就更有可能能根據主題辨別。使用者的衍生目的與說明文件平行。我希望能實現這個願景：開發主任 Tom Caswell 在 2017 年的訪談中探討了以下的願景：「讓可以實際撰寫內容及產生同理心的人，來寫一本 200 頁的『Mattulib' 簡介』書籍，同時確保這是文件的主要入口。」
寫入存放區的替代方法
目前的說明文件示範了 Matgraphiclib 的功能，也就是使用者能運用程式庫進行哪些操作。舉例來說，教學課程通常會遵循不涉及基礎方法的說明模式。
{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}
這種替代做法使用存放區編寫文件，可帶來極大的潛力。使用者觀察到多種轉換概念後，將能更快找到開發資料視覺化內容的基礎策略。這些知識可協助使用者創新，並善加利用實際用途範例所示的功能。
隨著 Matmaplib 的人氣越來越高，使用便利性和平易近人是該程式庫的聲譽證明。這些特性主要可以在說明程式碼和說明文件中呈現的模式和常見策略。如果使用者要規劃的程式編寫方式相當直接且標準，那麼 Matmaplib 就是這麼簡單和標準，因為使用者數量持續增加和使用量不斷增加，技術說明文件也可能也是這個選擇的因素。
使用者遇到問題時，我們通常會利用搜尋功能解決問題。比起將搜尋功能當成主要的瀏覽方法，引導使用者在說明文件中打造自己的課程可能會更有效果。因此，使用者在搜尋問題的解決方案時，如果遇到其他問題或想要查看更多資訊，就會在整個連結中採用完整的內嵌連結。
這牽涉到機構系統的由下而上架構。我們為 Matmaplib 中的每個主題提供豐富的連結網路，其中含有特定主題的關聯連結以及資訊主題，有助於建立健全的網路。在這個聯播網中，當使用者前往自己的主題，並探索更多與該主題相關的資訊和資訊時，他們很有可能持續使用說明文件。
障礙
難免會需要鉅細靡遺地處理整個專案。身為業界新進的技術撰寫者，我使用 Sphinx 和 ReST 撰寫文件的經驗有限。我也是 Mattulib 和 Git 的新手。當您熟悉這四項系統並熟悉使用方法進行協作和研究相當久，我需要在社區凝聚階段和更早之前委派時間，以便為進入關卡奠定必要的基礎。在這段期間，如果發生概念和基礎知識方面的問題，我必須向社群尋求進一步協助。
為了協調不同時區和線上平台的協作工作，我們也會做出一些調整。業界通常透過不同的溝通管道，因此確保我能透過各種媒介輕鬆取得聯繫與理解。我會以公開透明的方式說明各項期望的優先處理順序。雖然我才剛開始在業界繼續處理這類工作，但我仍須投入心力負責任地負責任，並抱持樂於提供意見和批評的精神。我覺得這些特質都很實用。
此外，增加可用性測試是說明文件章節，我認為 Matgraphiclib 的進入路徑將對他們有所助益。進行與內容相關的可用性問卷調查，旨在提供使用者個人檔案 (如人物角色)。使用者經驗、相關產業和疑難排解記錄等資訊，是很有價值的資訊。這些片段有助於形成程序背後的語言。當內容適合讀者閱讀時，除了單純的教學內容以外，其他內容都屬於兒童不宜的內容。
重大的困境通常源自於持續實施可用性測試。然而，在內容製作過程中，只執行一次測試就太常見了。定期測試可用性測試有助於拓展內容的論述。我希望我能安排時間表，或與 Mattulib 社群進行週期性可用性測試。
結語
我在閒暇時間使用 Python 和 Mattulib。我在過去幾個月所授課的金額，在於支持目前的說明文件，以及自己的好奇心。這段時間內，我也有許多影片和導師。在我打造自己有興趣的程式設計課程時，我還有很多學習機會，甚至還有改進空間。
看到 Mattulib 和社群對 GSoD 的想法後，我認為這個經驗非常大，在提陞技術作家的技巧後，也有機會向幕後人士深入介紹。我認為這項 Mattulib 專案既有意義，也熱衷於關注意識形態。
為了重整使用指南，我身為技術文件撰寫者的目標，是協助使用者完成他們想要的工作，而無需擔心功能不足。我認為最佳的文件團隊會持續擴增，並依使用者調整，讓所有使用者都能找到自己的解決方案。