用途:docs-style 是一份文档风格指南,适用于撰写新文档、更新已有文档,或对文档质量进行审查。它帮助作者判断文档类型并保持写法一致。
主要能力:提出多项写作原则,包括简洁无废话、面向任务而非罗列产品功能、渐进披露、用真实示例代替抽象解释、代码片段必须可直接复制粘贴(无占位值、无缺失导入)、前置说明先决条件、一页只讲一个主题、用链接代替重复内容、标题便于扫读、展示预期输出、术语统一、关键功能配截图或 GIF。它还要求区分教程、操作指南、参考和解释四类文档,不混写;教程应保证按步骤可完成,参考文档应详尽且结构一致。
语气与格式:要求不居高临下,尊重读者时间,先给命令或代码再解释;不塑造人格化语气,不用“Let's dive in”“Pro Tip”等表达,标题不用 emoji;优先把提示融入正文而非使用提示框,提示框仅留给数据丢失、安全等关键警告;示例要真实,且只在展示非显而易见语法、参数、管道或配置时保留;不写“Next Steps”结尾区块;页面标题与侧边栏标题一致;frontmatter 不使用 description 字段。标题应直接平实、便于扫读,避免教程章节式措辞。
使用方式与限制:资料未提供具体安装命令、配置方式或平台信息,暂未提供。该指南本身不包含可执行工具,仅作为写作与审查规范使用。