documentation

documentation 技能總覽

documentation 技能能做什麼

documentation 技能可協助你使用 Diátaxis 模型來建立、重組與審閱技術內容：tutorial、how-to guide、reference 和 explanation。當你需要的不只是一般寫作提示，而是希望文件結構能對應使用者意圖時，它特別有用。

誰適合使用它

如果你在撰寫產品文件、API 文件、上手流程，或內部開發者文件，這個 documentation 技能就很適合你。當你已經懂主題本身，但需要協助判斷正確的文件類型、調整大綱，或修正讓讀者看得霧煞煞的內容時，它尤其好用。

它的特色在哪裡

它的核心價值在於分類與結構，而不只是生成文字。documentation 安裝版的設計重點，是幫你把學習型內容和任務型內容分開，讓 reference 保持事實導向，並降低把說明、步驟和 API 細節混在同一頁的常見錯誤。

如何使用 documentation 技能

安裝並開啟正確的檔案

執行 npx skills add mcollina/skills --skill documentation 來安裝 documentation 技能。先從 SKILL.md 開始，再查看 tile.json 取得簡短摘要與中繼資料。由於這個 repo 沒有 rules/、references/ 或 scripts/ 資料夾，核心行為主要就來自主技能檔本身。

把模糊需求轉成有用的提示詞

這個技能在你提供文件目標、受眾與來源素材時效果最好。舉例來說，與其寫「幫我替 API 寫文件」，不如改成：「為需要用 API key 驗證我們 API 的新後端工程師寫一篇 how-to guide；請包含前置條件、設定步驟、一個成功範例，以及常見失敗情境。」這類輸入能讓 documentation 的使用更聚焦，也讓輸出更容易直接發布。

先用 Diátaxis 做判斷

在要求產出內容之前，先判斷使用者需要的是 tutorial、how-to guide、reference page 還是 explanation。tutorial 是透過實作來教；how-to guide 是解決單一任務；reference 記錄事實；explanation 則說明概念與取捨。如果跳過這一步，輸出雖然可能寫得順，但還是可能不符合 documentation guide 的標準。

提升輸出的建議流程

先讀產品原始筆記，再決定目標文件類型；如果範圍很大，先請這個技能產出大綱，再進入完整初稿。對 documentation 與 Technical Writing 來說，這通常比一開始就要整頁成稿更有效，因為你能更早修正範圍、術語和缺漏的前置條件。

documentation 技能常見問題

這比一般提示詞更好嗎？

如果結構很重要，答案是肯定的。一般提示詞可以幫你寫出文字，但 documentation 技能是先幫你選對文件模式，而這在技術寫作裡常常才是根本問題。

什麼情況下不該用它？

不要拿它來寫行銷文案、版本發布說明，或觀點型文章。當你只需要沒有脈絡來源的一個快速答案時，它也不是最佳選擇，因為文件工作通常還是要看受眾、限制與被記錄的任務。

它適合初學者嗎？

適合，只要你能用白話說清楚目標。初學者只要提供產品是什麼、讀者程度，以及要記錄的具體動作或概念，通常就能從 documentation 技能得到最大的幫助。

它適合 developer docs 和 API docs 嗎？

適合。documentation 技能很適合 API documentation、設定指南，以及內部開發者文件，尤其在你需要把 reference 資料和 tutorial 或 how-to guide 分開時，更是如此。

如何改進 documentation 技能

給技能正確的原始素材

最好的結果來自具體輸入：產品名稱、目標讀者、文件類型、目前狀態，以及讀者應該達成的精確結果。像「為第一次整合的使用者更新我們的驗證文件；他們需要產生 token 並測試一個 request」就比「改善我們的文件」強很多。

及早說明限制條件

先講明平台、版本、語氣、術語與任何政策限制。如果你的 documentation 安裝內容必須符合既有 style guide、特定 SDK，或 docs site 格式，請在產出前先說清楚；否則輸出可能在結構上沒問題，實際上卻還是不能用。

留意最常見的失敗模式

最大的問題通常是選錯 Diátaxis 類型、把說明混進步驟流程，以及用 tutorial 語氣去寫 reference 內容。如果初稿感覺太發散，請它拆成多個頁面、補齊更精準的前置條件，或重寫成把概念填充從任務步驟中移除的版本。

用有針對性的修改反覆調整

第一輪之後，請用一次只改一件事的方式優化 documentation 技能輸出，例如：「把這篇改成純 how-to guide」、「補上缺少的前置條件」、「把範例改成 API reference 風格」或「重寫給進階使用者看」。這種迭代方式通常比只要求一次全面潤飾，更能產出更好的 documentation guide。