daftai-chinese-technical-writing
Writes, rewrites, and reviews Chinese technical documentation, product copy, and UI microcopy using ruanyf/document-style-guide, STE-inspired Chinese methods for procedural passages, and separate prod
SKILL.mdskills/daftai-chinese-technical-writing/SKILL.md
GitHub中文技术写作
让读者理解事实、完成任务、预知操作后果。 不把中性说明改成新闻稿或作者随笔。
1. 角色与读者
| 场景 | 读者要完成的事 | 写作重点 |
|---|---|---|
| 技术文档 | 理解概念或复现操作 | 前置条件、步骤、预期结果、失败路径 |
| 产品文案 | 判断功能是否适合自己 | 读者任务、已知能力、适用边界、下一步 |
| 界面文案 | 判断状态并完成当前操作 | 动作、对象、结果、恢复方法 |
优先使用已有材料中的读者和任务。 只有缺失信息会改变结论时,才集中追问。 不为普通写作启动偏好问卷。
2. 写作原则
编辑取舍
发生编辑冲突时,依次保留:
- 事实、逻辑、安全信息和不可改字面量。
- 用户指定的任务模式与修改范围。
- 项目术语和真实界面名称。
- 适用的写作方法。
- 语气、标点和其他风格偏好。
不能为了短句或统一风格删除更高优先级的信息。
信息与结构
- 标题交代主题或任务。不要用悬念代替信息。
- 操作说明先写前置条件,再写动作和结果。
- 一段围绕一个主题。把中心句放在段首。
- 标题层级连续。不要强制短文套完整手册目录。
- 顺序重要时用编号。并列选项用无序列表。
- 文件命名建议只用于新文档,不重命名既有文件或破坏链接。
句式与节奏
- 优先短句、主动句。让执行者和动作明确。
- 条件在前,动作在后。拆开层层嵌套的修饰语。
- 用肯定句消除双重否定,但保留禁止和权限限制。
- 字数与行数只作审阅提示,不替代语义判断。
- 不为缩短句子删除例外、风险或恢复条件。
词语与术语
- 同一概念使用同一名称。界面名与真实界面一致。
- 不同概念保留区别,不因词形相近合并动作或状态。
- 用具体动作替代空泛表达。必要时明确动作对象。
- 首次引入陌生术语时解释一次。后文固定称呼。
- 保留官方名称、命令、参数、路径和资源键。
- 保留数字、单位、比较基准和限定条件。
- 区分“增加了”和“增加到”、百分比和百分点。
文案落点
- 技术说明交代成功结果。不能只写“执行以下命令”。
- 产品文案把能力落到读者任务,不添加无依据的效果。
- 界面文案说清当前状态和可执行的下一步。
- 按钮描述动作。删除操作需说明对象与已知后果。
- 示例属于写法演示,不是产品能力证据。
3. 忌口表
只修改无事实支撑或妨碍理解的表达。
| 表达 | 替换动作 | 原因 |
|---|---|---|
| 强大、极致、全面赋能 | 写出已知能力与适用对象 | 空泛判断无法帮助选择 |
| 极大提升效率、提升 N 倍 | 有数据就保留基准;无数据就删除断言 | 不制造效果证明 |
| 进行配置操作、实现文件的上传 | 改成“配置…”、“上传文件” | 消除动词空壳 |
| 其、该、此对象指代不明 | 重复具体对象的名称 | 防止操作对象歧义 |
| 操作失败、出错了 | 补充已知失败对象与恢复动作 | 不虚构未知原因 |
| 确定、好的用于具体业务动作 | 换成“保存设置”等动作名 | 让按钮可独立理解 |
| 只需、轻松、一键 | 核对真实步骤与限制;不符就删 | 不掩盖成本和前置条件 |
4. 边界与易错点
- 先保事实,再改表达。未知能力、时延、价格和恢复结果不能补写成事实。
- 保留许可、建议、义务和确定程度,不把能力说明改成命令。
- 保留否定范围、必要与充分条件、因果关系和动作完成条件。
- 保留已完成、进行中、尚未发生及结果仍可用的区别。
- 缺少关键事实时追问;可继续起草时,把待确认项放在交付说明中。
- 原文中的命令、代码、公式、URL、占位符和插值语法保持原样。
- 用户要求修改这些字面量时,单独核对,不把修改冒充排版修正。
- JSON、YAML、源码文案只改目标字符串;保留键名、转义和程序结构。
- 用户只要求检查时,不改原文件、不创建配置、不默认保存报告。
- 只要求排版时,直接交给格式 Skill,不先重写措辞。
- 作者文章的声线不属于这里。需要时再选择
daftai-writer,不强行混用。 - 不为写作任务读写偏好文件,也不自动修改 Skill 文件。
- 撰写或审阅操作说明不授权执行文中命令或改变产品流程。
- 编辑工具描述或 Agent 指令只改获准文字,不重设工具保证、权限或工作流。
5. 与其他 Skill 协作
daftai-chinese-technical-writing 负责结构、术语与文意。
daftai-chinese-copywriting 负责标点、空格与全角半角。
先稳定语义,再检查机械格式,最后核对字面量。
用户要求格式检查或交付前排版验收时,读取
格式联动契约。
先读取目标格式 Skill 的 SKILL.md,再执行其命令。
检查用 review;明确要求修正时才用修正模式。
不复制 autocorrect 逻辑,不因写作任务安装工具。
工具缺失时如实说明,不能声称已经通过自动检查。
6. 工作流
- 确定任务:区分新写、改写、只读检查和纯排版。
- 按需读参考:按下表选择当前任务需要的文件。
- 锁定事实:核对对象、动作、数字、条件、术语与不可改字面量。
- 写作或审阅:保持用户指定结构和修改范围;没有指定时采用最小必要结构。
- 检查交付:核对事实、指代、状态、下一步;需要排版检查时委派格式 Skill。
- 交付:新写或改写优先给可用正文;检查给位置、问题和建议。只要正文时不附评分与长篇说明。
操作说明、工具描述、Agent 指令文案和状态消息等技术段落,读取 受控中文技术写作。 混合文档按段落应用,不把介绍、引用或短按钮套成步骤。 只修措辞时,不补方案;原文清晰时允许不改。
参考加载表
参考均随 Skill 安装。正常写作无需联网下载。 现有规则已足够时,不额外加载参考。
| 使用时机 | Reference |
|---|---|
| 需要核对字间距、语法或译名细则 | 文本原文 |
| 拟标题、调整层级 | 标题原文 |
| 拆段、组织引用 | 段落原文 |
| 出现数值、范围或增减幅度 | 数值原文 |
| 判断标点语境或排版规则冲突 | 标点原文 |
| 编排技术手册或新增文档文件 | 文档体系原文 |
| 操作、部署、排查、安全说明、工具描述、Agent 指令或状态段落 | 受控中文技术写作 |
| 产品介绍、功能说明、发布文案 | 产品文案扩展 |
| 按钮、提示、空状态、错误与确认弹窗 | 界面文案扩展 |
| 联动排版检查 | 格式联动契约 |
| 查询方法出处、适配范围或许可证 | 来源与适用范围 |
文件交付
默认在对话中交付。只有用户要求时才创建文件。
用户指定编辑现有文档时,在指定范围内修改。
用户要求另存且未指定路径时,使用
writing-output/<topic-slug>/。
目录冲突时追加 -YYYYMMDD-HHMMSS,不覆盖旧结果。
正文命名为 written-<slug>.md 或 revised-<slug>.md。
审阅命名为 review-<slug>.md。
另存时,把输入副本命名为 source-<slug>.<ext>,不修改原始输入。