README 撰寫品質指南
RC1 規劃公開路由涵蓋 en 與 zh-Hant-TW；41 語系來源目錄為私有。本撰寫指南以英文版為準。
Better Workflows 的 README 是專案入口頁，不是壓縮版參考手冊。它應協助讀者依序回答五個問題：
- 這是什麼？適合我嗎？
- 它能解決什麼問題？
- 我為什麼能相信它的主張？
- 最快完成第一次成功操作的路徑是什麼？
- 接下來該看哪裡？
本指南定義每份儲存庫 README 在敘事、視覺、在地化與驗證方面必須遵守的要求。可供程式讀取的規格來源是 readme-quality-v1.json。
從讀者要做的決定出發
GitHub 通常會先呈現 README，再呈現儲存庫的其他內容。因此，第一個畫面必須說清楚產品能帶來什麼、適合誰，以及範圍明確的下一步。不要以內部架構、完整指令參考或版本復原細節作為開場。
請針對以下讀者需求撰寫：
- 首次造訪者：迅速判斷 Better Workflows 是否能解決自己的問題。
- 新使用者：安裝外掛，並成功完成一次自動路由。
- 評估者：了解授權邊界，以及條件不明或不符時停止執行的保守機制。
- 再次操作的使用者：直接找到工作流程、資安、架構或 CLI 的解答。
- 貢獻者或翻譯者：找到正式規格、開發指令、支援及治理資訊。
用因果關係組織敘事
五份入口頁 README 採用相同的八段語意順序。各語系的標題可以符合當地用語，但讀者的閱讀路徑不變。
| 段落 | 讀者問題與敘事作用 |
|---|---|
| 產品價值與適用對象 | Better Workflows 是什麼、為何存在，又適合誰？ |
| 從問題到成果 | 把意圖、授權、證據與服務提供者的實際結果混為一談，會出什麼問題？ |
| 佐證與邊界 | 哪些保證讓預期成果可信？ |
| 第一次成功操作 | 從安裝到取得結果，最短的完整路徑是什麼？ |
| 選擇下一步 | 哪個工作流程或文件符合讀者的目標？ |
| 生命週期 | 目標如何成為經核對的完成結果，或在必要時安全停止？ |
| 信任與限制 | 系統絕不能自行推論、授權或宣稱什麼？ |
| 學習、求助與貢獻 | 深入文件、支援、治理、開發與授權條款在哪裡？ |
這個順序形成實用的敘事脈絡：
- 背景：提示詞驅動的工作可以表達意圖，卻不代表授權或狀態已獲證明。
- 問題：會改變系統狀態的操作，使這個缺口成為交付風險。
- 解法：Better Workflows 將目標、範圍、證據、審查、操作與服務提供者結果核對綁定。
- 佐證：透過明確的保證與邊界，說明解法如何運作。
- 行動：先讓讀者完成第一次成功操作，再介紹深入實作細節。
- 延伸：依角色與預期成果，引導讀者前往適合的教學、操作指南、概念說明或參考資料。
區分入口頁內容與深入文件
README 應提供有助於做決定的資訊。依用途引導讀者深入閱讀：
- 入門指南是初次使用的教學。
- 工作流程是依預期成果選擇操作方式的指南。
- 架構說明控制平面與設計取捨。
- 資安說明授權、隱私、簽證，以及條件不明或不符時停止執行的機制。
- CLI 參考是指令參考文件。
- 在地化的
docs/details/*.md頁面保留完整的翻譯細節。
不要在入口頁重複放入快取復原、鎖定所有權、服務提供者傳輸的完整語意、所有指令或實作變更歷史。入口頁只需保留簡潔的安全主張；可供稽核的深入說明應放在正式指南中。
這種區分遵循 Diátaxis 對教學、操作指南、概念說明與參考資料的分類。同一頁面無法同時最佳化這四種閱讀需求。
每張圖都要有明確用途
只有在關係、層級或狀態轉移用圖像呈現明顯比文字更容易理解時，才使用圖像。
入口頁允許使用兩種圖：
- 授權邊界架構圖：說明哪些層級決定意圖、目前事實、工具權限、次數受限的重試與唯讀狀態。
- 從目標到完成的生命週期圖：說明何時檢查證據、何時授權會改變狀態的操作，以及何時因狀態不明而停止。
每張圖都必須包含：
- 簡潔且有意義的替代文字；
- 緊鄰圖像的等義文字，確保隱藏圖像或 Mermaid 無法顯示時，仍能理解相同結論；
- 盡可能以真正的文字呈現重要標籤；
- 一個明確且持續適用的讀者問題，作為持續更新該圖的理由。
不要加入裝飾性截圖、塞滿文字的圖片，或只是重述短清單的圖表。選擇表應維持兩個精簡欄位，讓窄螢幕也能閱讀。
各語系維持相同含義
英文是語意基準，不是行數目標。繁體中文、簡體中文、日文與韓文應讓母語讀者讀起來自然，同時保留相同的規範含義。
以下項目必須保持等義：
- 八個語意段落及其順序；
- 第一次成功操作的指令與產品識別碼；
- 授權、證據、未知狀態、提示詞與隱私等五項主張；
- 工作流程、資安、架構、CLI、支援、治理、開發與授權條款的連結目的地；
- 圖像用途、生命週期階段與替代文字說明；
- 版本來源與徽章規範。
標題、分句、標點、範例與行動引導可以符合當地習慣。絕不可翻譯指令、選擇器或證據識別碼，也不可改變安全規範的語意。
方便快速閱讀與翻譯
- 先說讀者能得到什麼結果，並把重要詞語放在標題及段落開頭。
- 使用主動語態，指明由誰負責操作。
- 撰寫操作程序時，直接對讀者說明。
- 段落要短，每段只處理一件事。
- 有順序的步驟使用編號清單，沒有先後關係的選項使用項目清單。
- 使用具體的連結文字，不要只寫「按這裡」。
- 標題層級要清楚、內容要具體，同一層級的表述應一致。
- 優先使用明確、沒有歧義且容易保留原意的語句。
- 先寫適用條件，再寫操作指示；指令之後再寫預期結果。
驗證含義，不只檢查外觀
文件測試不能只比對標題，還必須檢查：
- 只有一個 H1，且標題層級合理；
- 語意段落與關鍵主張的標記順序正確；
- 第一次成功操作的指令與穩定識別碼完全一致；
- 相對連結及各語系的詳細文件目的地正確；
- 版本徽章與執行階段中繼資料一致；
- 圖像替代文字有意義，且附有緊鄰的文字替代說明；
- 只有一張 Mermaid 生命週期圖，並附完整的等義文字；
- 表格維持兩欄，段落長度不超過限制；
- 入口頁不包含已指定應移至深入文件的實作細節；
研究依據
- GitHub：儲存庫 README 檔案說明界定 README 在初次造訪時的用途，並建議將長篇文件移至其他位置。
- Diátaxis區分教學、操作指南、概念說明與參考資料的需求。
- Microsoft：便於快速閱讀的內容強調重要資訊優先、短段落與一致的視覺閱讀起點。
- Google 開發者文件風格指南建議使用主動語態、直接對讀者說明、具體標題、無障礙設計及適合全球讀者的寫法。
- GitHub：建立圖表說明 Markdown 的 Mermaid 支援。
- W3C WAI：圖片教學要求資訊性與複雜圖像提供替代文字及完整的等義說明。