Skip to content

WizerdBaChe/diagram-audience-fit / reference-impl/skills/audience-fit

audience-fit

Verified

Post-production audience-adaptation pass (受眾調校) for anything a NON-BUILDER reads: (A) turn an engineering-voiced deliverable (report, summary HTML, README, release notes) into a reader-facing version in a NEW file, or draw a NEW diagram for a non-builder reader (README flow, promo image, audience page) even with no original; (B) write or fix UI copy (設定頁、狀態列、錯誤訊息) from the user's stance, not the engine's. Trigger on 「使用者導向」「白話版」「寫給非工程師看」「UI 文案」「這段太工程」「AI味」 "rewrite for end users"; OFFER once, unprompted, after any skill produces a deliverable whose primary consumer is not its builder. NOT machine-read docs (phase logs, specs), NOT layout/theming (→ artifact-design), NOT technical docs from code (→ engineering:documentation), NOT task/flow/state evaluation 「走得通嗎」「停用還是隱藏」 (→ ux-walkthrough; findings hand off both ways).

references/project-info-for-general-readers.md

View on GitHub
# 技術專案的一般使用者導向資訊提供指南

> **適用範圍**:任何技術專案的對外資訊,包括功能說明、使用方式、安裝與設定、架構概覽、可靠性與安全、限制與風險、維護與支援、版本更動等。
>
> **目標**:保留技術專案的完整性與可追溯性,但將表達方式調整為「具基本電腦使用經驗、未必具備開發背景」的讀者可以理解與使用。
>
> **不追求的目標**:行銷化、把技術細節全部刪除、或把未驗證的工程狀態寫成對使用者的承諾。

---

## 專案資訊全景

```yaml
project_information_landscape:
  user_facing:
    - "功能與價值:這個專案能做什麼、對使用者有何幫助"
    - "使用方式:如何開始、主要流程、常見情境"
    - "安裝與設定:需求、步驟、驗證方式"
    - "帳號、權限與資料:誰能用、能看到什麼、資料如何保存"
    - "可靠性與安全:系統如何避免出錯、資料如何保護"
    - "限制與風險:已知問題、影響範圍、暫時處置"
    - "維護與支援:如何回報問題、回應時間、文件與教學"
    - "版本更動:新版本改了什麼、對使用者有何影響"

  architecture_facing:
    - "系統分層與元件責任"
    - "主要資料流與任務流程"
    - "狀態、例外與恢復機制"
    - "測試、監控與量測方法"

  engineering_only:
    - "原始碼路徑、類別與函式名稱"
    - "內部路由、參數、腳本與自動化流程細節"
    - "完整狀態矩陣、差分表、提交雜湊"
    - "僅供維護者使用的診斷與除錯資訊"

  mapping_principle: "user_facing 為正文主軸;architecture_facing 以概覽與附錄形式支援;engineering_only 僅在技術附錄或內部文件出現"
```

一般使用者不需要知道「程式碼在哪裡」,但需要知道「功能在哪裡、怎麼用、出問題怎麼辦」。工程細節仍應保留,但應放在讀者可選的附錄,而不是理解正文的必要前提。

---

## 讀者分群與對應資訊

```yaml
reader_profiles:
  end_user:
    description: "主要使用者,關心功能、流程、限制與支援"
    needs:
      - "功能與價值"
      - "使用方式與流程"
      - "安裝與設定(若需本地安裝)"
      - "限制、風險與已知問題"
      - "支援管道與回報方式"
    depth: "能完成任務、理解限制、知道出問題找誰"

  power_user:
    description: "進階使用者,可能自行整合或自動化"
    needs:
      - "end_user 全部內容"
      - "架構概覽與資料流"
      - "設定檔、API 或匯出格式的簡要說明"
      - "更詳細的錯誤訊息與日誌解讀指引"
    depth: "能自行調整設定、解讀錯誤、撰寫簡單整合"

  evaluator:
    description: "評估是否採用此專案的人(主管、採購、合作單位)"
    needs:
      - "功能與價值"
      - "可靠性、安全與合規概況"
      - "成本、資源需求與維護負擔"
      - "限制、風險與替代方案"
    depth: "能做出採用或不採用的決策"

  maintainer:
    description: "未來可能維護或擴展此專案的人"
    needs:
      - "完整架構與工程文件"
      - "測試、監控與部署流程"
      - "已知技術債與待決策項目"
    depth: "能理解系統全貌並進行修改"

  document_strategy: "以 end_user 為預設讀者,提供 power_user 與 evaluator 的延伸章節,maintainer 資訊放在技術附錄或獨立工程文件"
```

同一份文件可以服務多種讀者,但必須有清楚的「閱讀路徑」:一般使用者讀正文即可,進階讀者可依指引跳到特定章節,維護者則有獨立的技術附錄。

---

## 資訊分層(專案級)

```yaml
project_information_layers:
  layer_0_overview:
    question: "這個專案是什麼、能幫我做什麼?"
    content:
      - "一句話說明:用途、輸入、輸出"
      - "主要功能清單(3 至 7 項)"
      - "典型使用情境(1 至 3 個)"
    avoid:
      - "技術架構、安裝細節、版本歷史"

  layer_1_getting_started:
    question: "我要如何開始使用?"
    content:
      - "前置需求:帳號、硬體、軟體、權限"
      - "快速開始步驟(3 至 7 步)"
      - "驗證方式:如何確認已成功"
      - "下一步建議:教學、範例、常見任務"
    avoid:
      - "完整功能列表、所有設定選項、邊界情況"

  layer_2_usage_guide:
    question: "我該如何完成各種任務?"
    content:
      - "主要任務流程(例如建立、處理、輸出)"
      - "進階功能與設定(依情境分章)"
      - "錯誤訊息與排解步驟"
      - "最佳實踐與常見錯誤"
    avoid:
      - "內部實作細節、未公開的 API 或參數"

  layer_3_reliability_and_safety:
    question: "系統可靠嗎?我的資料安全嗎?"
    content:
      - "可靠性措施:測試、監控、備份、恢復"
      - "安全與隱私:資料流向、加密、權限控制"
      - "已知限制與風險:條件、影響、狀態、處置"
    avoid:
      - "把測試數量誤寫為可靠度保證"
      - "未經驗證的安全宣稱"

  layer_4_maintenance_and_support:
    question: "出問題怎麼辦?如何獲得協助?"
    content:
      - "支援管道:文件、社群、客服、回報表單"
      - "回應時間與服務範圍"
      - "維護視窗、更新方式與影響"
    avoid:
      - "內部除錯流程、未定案的維修策略"

  layer_5_changes_and_versioning:
    question: "新版本改了什麼?會影響我嗎?"
    content:
      - "功能導向的變更摘要"
      - "相容性與資料遷移說明"
      - "升級步驟與回滾方式"
    avoid:
      - "以 commit、branch、檔案增減作為主敘事"

  layer_6_technical_appendix:
    question: "我想深究技術細節,哪裡可以看?"
    content:
      - "架構概覽與資料流圖"
      - "術語表與縮寫對照"
      - "測試範圍與量測方法摘要"
      - "工程文件連結或參考"
    rule: "不得成為理解正文的必要前提"
```

正文應依「理解順序」而非「工程完成順序」排列。讀者先知道「這是什麼、怎麼用、安不安全」,才有動機與能力理解「背後如何運作」。

---

## 各區塊寫作指引

### 功能與價值

```yaml
function_and_value:
  required_elements:
    - "一句話說明:用途、輸入、輸出"
    - "主要功能清單(3 至 7 項,以使用者任務命名)"
    - "每個功能對應的使用者收益"
  sentence_templates:
    - "這個專案能幫你把{輸入}轉換成{輸出},用於{用途}。"
    - "主要功能包括:{功能 1}、{功能 2}、{功能 3}。"
    - "當你{情境}時,系統會{行為},讓你能{收益}。"
  avoid:
    - "以技術元件名稱作為功能名稱"
    - "未經驗證的效率、準確率或成本宣稱"
```

### 使用方式與流程

```yaml
usage_and_flow:
  required_elements:
    - "主要任務流程圖或步驟列表"
    - "每個步驟的使用者行動與系統回應"
    - "常見錯誤與排解方式"
  sentence_templates:
    - "典型流程為:{步驟 1} → {步驟 2} → {步驟 3}。"
    - "在{步驟}時,系統會{行為};你可以{行動}。"
    - "若遇到{錯誤},通常表示{原因};建議{處置}。"
  action_rules:
    - "動作句把觸發條件放前面:「若遷移回報結構不符,先回滾再重試。」"
    - "讀者讀完要動手或驗證時,以勾選清單收尾,一項一個具體檢查(來源:tt-a1i/archify explainer-authoring,借用帳 B-17)"
  avoid:
    - "把內部狀態機完整展開成正文"
    - "忽略中斷、失敗與恢復的使用者視角"
```

### 安裝與設定

```yaml
installation_and_setup:
  required_elements:
    - "前置需求:硬體、軟體、帳號、權限"
    - "安裝步驟(依平台分節)"
    - "驗證方式:如何確認安裝成功"
    - "基本設定與進階設定的界線"
  sentence_templates:
    - "在開始之前,你需要{需求清單}。"
    - "安裝步驟為:{步驟 1}、{步驟 2}、{步驟 3}。"
    - "安裝完成後,你可以透過{驗證方式}確認成功。"
  avoid:
    - "把除錯選項與實驗性功能寫入主要流程"
    - "假設讀者已知環境變數、路徑或權限概念"
```

### 可靠性與安全

```yaml
reliability_and_safety:
  required_elements:
    - "可靠性措施:測試、監控、備份、恢復"
    - "安全與隱私:資料流向、加密、權限"
    - "已知限制與風險:條件、影響、狀態、處置"
  sentence_templates:
    - "系統透過{措施}來降低{風險}。"
    - "你的資料會{流向},並使用{保護方式}。"
    - "在{條件}下,可能發生{問題};影響為{結果};目前{狀態};你可以{處置}。"
  evidence_rule: "每一個可靠度或安全相關宣稱,必須有可追溯的測試、設計文件或量測依據"
  avoid:
    - "由測試數量直接推算錯誤率或可用性"
    - "把設計目標寫成已實現的保證"
```

### 限制與風險

```yaml
limitations_and_risks:
  required_fields:
    - "問題是什麼"
    - "在什麼條件下發生"
    - "使用者會看到或受到什麼影響"
    - "目前修正、驗證或決策狀態"
    - "使用者可做的暫時處置;若沒有,明確寫無"
  severity_labels:
    critical: "主要功能無法使用、資料可能遺失或安全性風險高"
    warning: "特定條件下結果可能不正確、需檢查或重試"
    note: "行為限制存在,但通常不會阻斷核心流程"
    open: "原因、語意或處理方式尚未定案"
  style:
    - "直接陳述,不使用模糊的『可能有些小問題』"
    - "不將已知缺陷藏在附錄或腳註"
    - "不承諾尚未排定或尚未驗證的修正時間"
```

### 維護與支援

```yaml
maintenance_and_support:
  required_elements:
    - "支援管道:文件、社群、客服、回報表單"
    - "回應時間與服務範圍"
    - "維護視窗、更新方式與影響"
    - "使用者可做的自助排解步驟"
  sentence_templates:
    - "若遇到問題,你可以透過{管道}尋求協助。"
    - "一般回應時間為{時間},涵蓋{範圍}。"
    - "系統會在{時間}進行維護,可能影響{功能}。"
  avoid:
    - "內部除錯流程或未定案的維修策略"
    - "把內部優先級直接暴露成使用者承諾"
```

### 版本更動

```yaml
version_changes:
  required_elements:
    - "版本號與發布日期"
    - "功能導向的變更摘要"
    - "相容性與資料遷移說明"
    - "升級步驟與回滾方式"
  sentence_templates:
    - "此版本新增了{功能},改進了{行為},修正了{問題}。"
    - "對使用者的影響為:{影響說明}。"
    - "升級步驟為:{步驟};若需回滾,可{方式}。"
  avoid:
    - "以 commit、branch、檔案增減作為主敘事"
    - "把內部重構寫成使用者可見的功能改變"
```

---

## 名詞與語氣規則(專案級)

```yaml
language_rules_project:
  principle:
    - "先寫功能與結果,再補上技術名稱"
    - "首次出現的必要術語採『白話名稱(英文或技術名稱)』格式"
    - "每個段落最多引入一到兩個新術語"
    - "以主動語態描述誰做什麼,以及結果是什麼"
  preferred_patterns:
    - "這個專案能幫你{完成任務},透過{主要流程}。"
    - "在{情境}時,系統會{行為},因此{結果}。"
    - "若{條件},你可能看到{現象};建議{處置}。"
    - "此版本已{變更},對你的影響是{影響}。"
  avoid_patterns:
    - "以縮寫或檔名作為句子的主詞"
    - "未解釋即使用多個名詞串接"
    - "把內部實作機制誤寫成使用者可感知的功能"
    - "用『穩定』『安全』『快速』等空泛形容詞取代證據"
  terminology_format:
    first_mention: "任務狀態機(state machine,管理任務可前往哪些狀態的規則)"
    later_mention: "任務狀態規則"
    appendix: "保留精確術語、縮寫與原始名稱"
```

---

## 視覺化分工(專案級)

```yaml
visualization_guide_project:
  overview_map:
    question_answered: "這個專案由哪些部分組成?"
    recommended_form: "三至五層的分層架構圖"
    nodes:
      max_recommended: 7
      naming: "以職責或使用者可見功能命名"
    connectors: "只畫主要資料流或控制流"

  user_flow:
    question_answered: "完成一個典型任務需要哪些步驟?"
    recommended_form: "由左至右或由上至下的流程圖"
    nodes: "用使用者可理解的狀態與行動"
    branches: "只保留會造成不同使用者行動的例外分支"

  status_explanation:
    question_answered: "現在發生什麼?我能做什麼?"
    recommended_form: "狀態卡、進度條或簡化狀態圖"
    include:
      - "目前狀態"
      - "系統正在做的事"
      - "使用者可以採取的行動"
      - "下一個可能結果"

  trust_dashboard:
    question_answered: "系統目前健康嗎?有哪些限制?"
    recommended_form: "摘要卡加上風險表"
    categories:
      - "已驗證:有測試或檢查證據"
      - "已知限制:清楚說明觸發條件與影響"
      - "進行中:尚未完成驗收或修正"

  change_overview:
    question_answered: "新版本改了什麼,會影響我嗎?"
    recommended_form: "功能導向的前後對照表"
    translate:
      - "新增節點數 → 新增哪些能力"
      - "修改檔案數 → 哪些使用流程改變"
      - "結構差異 → 相容性、資料遷移或行為改變"

  installation_diagram:
    question_answered: "我需要準備什麼、安裝後會變成怎樣?"
    recommended_form: "前置需求清單 + 安裝後架構簡圖"
    include:
      - "本地與雲端元件的界線"
      - "資料存放位置與流向"
      - "必要帳號與權限"
```

---

## 量化與證據規則(專案級)

```yaml
evidence_rules_project:
  allowed_claims:
    - "可由測試、監控、量測或明確紀錄支持的敘述"
    - "附帶範圍、時間點與測量對象的數字"
    - "明確區分已驗證、設計中與已知問題"
  forbidden_inference:
    - "由測試通過數直接推算錯誤率、準確率或服務可用性"
    - "由模組數、程式碼量或圖上節點數推論功能品質"
    - "將尚未跑完的使用者驗收測試寫成已可保證"
  recommended_template:
    claim: "已完成什麼檢查"
    scope: "檢查涵蓋何種流程或版本"
    limit: "此證據未涵蓋什麼"
    status: "目前結果與後續處置"
```

例如,「通過 2,100 項自動化測試」是可呈現的工程證據;但除非另有統計設計與測量依據,不能因此寫成「錯誤率低於 0.1%」或「穩定度 99.9%」。原始資料顯示測試通過數與尚未執行的使用者驗收項目必須分開揭露,而不是互相抵銷。[cite:file:1]

---

## 改寫工作流程(專案級)

```yaml
rewrite_workflow_project:
  step_1_inventory:
    action: "盤點現有文件中的所有資訊:功能、使用、安裝、架構、測試、風險、維護、版本"
    output: "內容清單,標記為 user_facing、architecture_facing、engineering_only"

  step_2_map_to_readers:
    action: "將每項資訊對應到 end_user、power_user、evaluator、maintainer"
    output: "讀者 × 資訊對應表"

  step_3_define_layers:
    action: "依 project_information_layers 定義正文與附錄的界線"
    output: "章節大綱與每章的讀者問題"

  step_4_translate:
    action: "套用各區塊的句子範本與語言規則"
    output: "白話正文與可追溯的技術附錄"

  step_5_draw:
    action: "為每個主要讀者問題設計一張圖"
    output: "概覽圖、流程圖、狀態卡、風險表、變更表"

  step_6_verify:
    action: "由技術審查者檢查事實,由不同讀者檢查理解"
    output: "事實正確且多類讀者可理解的版本"

  step_7_maintain:
    action: "專案更新時,同步更新功能、流程、限制、風險與版本章節"
    output: "不隨版本演進而失真的說明文件"
```

---

## 發布前檢核表(專案級)

```yaml
release_checklist_project:
  whole_document:
    - "開頭是否在三句內說清楚專案用途、輸入與輸出?"
    - "讀者是否能在不看附錄的情況下理解主要功能與流程?"
    - "章節是否依理解順序,而非依工程完成順序排列?"

  terminology:
    - "必要術語是否首次出現就有白話說明?"
    - "縮寫是否避免成為主要敘事?"
    - "檔案名稱、路徑與版本識別是否已移至附錄?"

  diagrams:
    - "每張圖是否只回答一個主要問題?"
    - "節點是否以責任或讀者可見狀態命名?"
    - "箭頭、顏色、圖示與例外分支是否有一致含義?"
    - "是否保留中斷、失敗與恢復的讀者視角?"

  evidence:
    - "每一個數字是否附有範圍、時間點或測量意義?"
    - "是否避免將測試數量誤寫為可靠度、準確率或零錯誤保證?"
    - "已知限制是否寫出條件、影響、狀態與暫時處置?"

  reader_test:
    - "end_user 能否說明專案能做什麼、如何開始、出問題找誰?"
    - "power_user 能否找到進階設定與錯誤解讀指引?"
    - "evaluator 能否理解可靠性、安全、成本與限制?"
    - "maintainer 是否有足夠技術附錄進行維護?"
```

---

## 最小正文骨架(專案級)

```yaml
recommended_outline_project:
  - "這個專案是什麼:用途、輸入、輸出、主要功能"
  - "快速開始:需求、安裝、驗證、下一步"
  - "使用指南:主要任務流程、進階功能、錯誤排解"
  - "可靠性與安全:測試、監控、資料保護、已知風險"
  - "限制與已知問題:條件、影響、狀態、處置"
  - "維護與支援:管道、回應、維護視窗、自助排解"
  - "版本更動:功能導向變更、相容性、升級與回滾"
  - "名詞說明與技術附錄:供需要深究的讀者查閱"
```

---

## 與架構指南的關係

```yaml
relation_to_architecture_guide:
  overlap:
    - "資訊分層原則"
    - "名詞與語氣規則"
    - "視覺化分工與圖表語法"
    - "量化與證據規則"
  extension:
    - "從架構擴展到功能、使用、安裝、維護、版本"
    - "增加讀者分群與對應資訊策略"
    - "增加各區塊的寫作範本與檢核項目"
  usage_recommendation: "若只需調整架構章節,參考《一般使用者導向架構說明寫作指南.md》;若需調整整個專案文件,使用本指南作為主軸,並視需要引用架構指南的細節"
```

這份文件設計為「技術專案對外資訊的總指導書」。你可以把它當作模板,針對特定專案(例如本地工具、雲端服務、API 平台)再微調各區塊的權重與範例。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall