SuperAPI AI 工具集

technical-writing

写作与研究

查看项目

更新于 10-15 16:46

技能介绍

该技能用于编写清晰、完整的技术文档,适用于撰写技术规格、架构文档、系统设计说明、运维手册(runbook)、开发者文档、API 文档、用户手册以及发布说明和变更日志。

使用流程分为五步。第一步是理解受众:面向开发者时侧重实现细节、代码示例与技术术语;面向 DevOps 与运维时侧重部署维护、配置示例、监控排障与运维手册;面向管理者时侧重高层概览、业务影响与结果;面向终端用户时使用简单语言、分步说明、图示与常见问题。第二步是选择文档类型,技能提供了技术规格、架构文档、运维手册、API 文档、README 与变更日志等模板,其中技术规格包含问题陈述、目标与非目标、方案设计、实施计划、测试与安全等章节;架构文档包含组件、数据流、关键技术决策与技术栈等;运维手册包含部署、回滚、监控指标、告警、常见问题与应急联系人。第三步给出写作规范:语言直接、一句一个观点、段落简短、定义术语、使用层级标题与表格、提供代码示例与前置条件、覆盖错误处理与边界情况、保持术语与格式一致。第四步介绍图示与辅助元素,如 Mermaid 架构图、时序图、流程图,带语法高亮的代码块、截图与参数表格。第五步是自查与维护,包括目的明确、术语已定义、示例经测试、格式一致、标注更新日期,并让目标受众试读,随代码变化更新文档。

技能还列举常见错误(假设读者已有知识、文档过时、缺少示例与图示、结构混乱、被动语态、术语过多、缺少错误场景、缺乏维护)与最佳实践,并列出图示、文档平台、风格检查与截图类工具。使用该技能需要相应写作或文档环境,具体平台与工具可能需另行安装配置,资料未提供固定的安装命令、收费方式或授权信息。