SuperAPI AI 工具集

explanation-docs

写作与研究

查看项目

更新于 10-15 21:39

技能介绍

用途:该技能提供解释型文档(explanation)的写作模式。解释型内容以理解为导向,回答“为什么”和“如何运作”,而非“怎么做”,适合想深入理解概念的用户、评估设计决策的架构师与技术负责人、上手代码库的新成员。

主要能力:提供统一的说明文档模板,包含标题与描述前言、概述、背景与上下文(问题与历史)、如何运作(核心概念、机制、关键组件)、设计决策与取舍、备选方案、影响与后果、相关概念等章节。同时给出写作原则:聚焦理解而非操作、使用类比与心智模型、解释设计背后的原因、诚实讨论取舍、按反思而非行动组织内容、明确表达观点与判断、连接更大图景。还提供图示(如 mermaid)、对比表格、Note/Warning 提示、Expandable 折叠区块等组件用法,以及发布前检查清单和按顺序执行的完成门槛(分类、骨架、理由、清单)。

使用方式:资料说明需与 docs-style 配合使用,以获取核心写作原则;如不确定应写解释型还是教程、操作指南或参考文档,可查阅 docs-style/references/diataxis-compass.md。文档需按模板和检查清单撰写并逐项通过门槛。

适用场景:撰写以理解系统设计为目的的概念指南,适用于架构说明、设计权衡分析、系统运作原理介绍等。

限制:文档中明确该类型容易被误用,需避免混入手把手操作步骤或参数表,否则应改为 How-To 或 Reference 并链接过去;具体安装或命令资料未提供。