技术写作指南生成器

📝 核心原则

• 原则：任务导向，逐步可操作 描述：围绕用户要完成的具体任务来组织内容；每步只含一个动作，提供“成功判定”和“下一步”。 优先级：5

• 原则：一致性与准确性（UI/型号/术语） 描述：文档中的按钮名、页面名、设备型号必须与App和设备一致；混写不同型号严禁；术语统一并附英文小字。 优先级：5

• 原则：最新、可视化、可验证 描述：使用最新界面截图（标注App/固件版本与日期），大图清晰注解，用户可按图验证当前界面是否一致。 优先级：5

• 原则：可诊断性（判定标准＋决策分支） 描述：故障排查不止列现象；为每一步给出“观察点/阈值/如果…则…”的判断与分支，直到可执行的解决方案或求助。 优先级：5

• 原则：安全优先 描述：用电与网络安全提示前置且重复出现；高风险步骤使用警示图标、红色边框与明确后果说明。 优先级：4

• 原则：可访问性优先 描述：颜色对比达标（≥4.5:1）、图示均配文字、视频有字幕；信息不依赖颜色唯一信号。 优先级：4

• 原则：面向非技术用户的简明表达 描述：短句、常用词、主动语态；避免行话与缩略语，如需使用，首次出现时解释并附英文小字。 优先级：4

• 原则：版本可追溯与变更可控 描述：在页眉或封面明确设备型号、App/固件版本、发布日期；变更记录清晰；截图与步骤与版本绑定。 优先级：4

✍️ 写作风格指南

• 指南：一步一操作，动词开头 示例：在“首页”(Home)点“添加网关”(Add Gateway)。 注意事项：避免并列动作；用“>”表示路径：设置(Settings) > 网络(Network)。

• 指南：使用与App一致的原文按钮名 示例：点“下一步”(Next)，不要写“继续”。 注意事项：按钮名必须一字不差；若App多语言，文档以中文为主，英文小字附于首次出现处。

• 指南：前置条件＋预计耗时 示例：准备好2.4 GHz Wi‑Fi、网关、电源适配器；预计用时5分钟。 注意事项：明确网络限制（如不支持5 GHz）；列出必要工具和账号权限。

• 指南：提供成功判定与下一步 示例：看到网关指示灯常亮（绿）即成功；继续在App选择“绑定设备”(Bind)。 注意事项：描述指示灯颜色与状态；给出异常分支入口。

• 指南：使用短句与常用词，主动语态 示例：把网关接入电源。不要写：电源应被接入。 注意事项：句长≤20字；避免堆叠从句。

• 指南：图大字清，统一注解风格 示例：编号标注1、2、3；红框突出点击区域；图下注明App 3.2.0/拍摄日期。 注意事项：截取实际设备/界面；不要使用示意图替代关键步骤。

• 指南：视频短链与二维码并存 示例：观看1分钟配网视频：https://… 或扫码。 注意事项：视频需字幕与静音可看；封面帧展示目标界面。

• 指南：型号明确与分流 示例：选择你的型号：GW‑100｜GW‑200；选错型号？点这里重新选择。 注意事项：每个型号有独立章节与清晰跳转；禁用“通用步骤”覆盖差异。

• 指南：故障排查用If/Then与可测标准 示例：如果路由器距离>10米，则移动至5米内再试；若RSSI<-70 dBm，建议换位。 注意事项：提供测量方法与工具位置截图。

• 指南：安全提示模板化 示例：[警告] 拔插电源前先断电；操作湿手会触电危险。 注意事项：用危险/警告/注意分级；说明后果与避免方法。

• 指南：链接可读，不用“点击这里” 示例：查看路由器设置指南：https://…/router-2g 注意事项：为链接添加用途描述；检查有效性与跳转目标。

• 指南：一致的数字与单位 示例：2.4 GHz、5 分钟、3 次重试。 注意事项：阿拉伯数字+标准单位；时间给出范围或上限。

• 指南：术语首现解释＋英文小字 示例：配网（将设备连接到家庭网络，Provisioning）。 注意事项：术语统一收录在术语表；避免同义词混用（绑定=配对？二选一）。

• 指南：每节结尾提供FAQ与客服入口 示例：常见问题：…；仍需帮助？在线客服（7×24）：400‑xxx‑xxxx。 注意事项：FAQ按发生率排序；提供工单所需信息模板。

🔧 文档结构 | 元素 | 目的 | 最佳实践 | |------|------|-----------| | 封面与元数据 | 明确适用范围与版本 | 标注设备型号、支持固件、App版本、发布日期、文档编号与适用地区 | | 快速开始（3–5步） | 新手快速上手 | 仅保留关键路径；每步配大图与成功判定；提供1分钟视频链接 | | 准备材料与环境 | 降低安装失败 | 列工具/账号/网络要求（2.4 GHz/IPv4）；预计耗时；前置检查清单 | | 型号识别与选择 | 防止混写与误操作 | 以图片与标签区分型号；为每型号建立独立流程与跳转 | | 安全警示 | 降低风险 | 危险/警告/注意分级；放在相关步骤前；图标+文字+后果 | | 安装与接线 | 正确物理连接 | 一图一接口；颜色/形状对照；提供反例（错误插法） | | 配网与账户绑定 | 连网与激活设备 | 指明仅支持2.4 GHz；示例填写Wi‑Fi；展示权限弹窗处理 | | App 首次引导 | 完成基础设置 | 截图与按钮名一致；提供“跳过”后果说明；隐私与数据权限提示 | | 常用任务（用户手册） | 提升采用率 | 任务卡片化：任务目标、步骤、成功判定、耗时；示例：添加子设备、创建自动化 | | 操作手册（运维/日常） | 稳定运行 | 例行检查、重启流程、备份与恢复；提供维护频率与责任人 | | 故障排除总览 | 快速定位问题 | 以症状入口组织：无法配网/离线/指示灯异常；每项链接到决策树 | | 决策树与判定标准 | 可执行排障 | If/Then分支；每步包含观察点、工具、阈值与下一步 | | 错误提示与代码对照 | 缩短诊断时间 | 显示文案、可能原因、解决步骤、何时联系支持 | | 维护与固件更新 | 保持最新与安全 | 更新前备份与回滚；断电风险提示；版本差异说明 | | 网络与安全建议 | 提升可靠性与安全 | 路由器设置（信道/带宽）、密码强度、访客网络、远程访问建议 | | 常见问题（每节结尾） | 及时解答 | 基于工单热度排序；短问短答；必要时指向视频 | | 客服与支持入口 | 获取人工帮助 | 电话/在线/邮件/工作时间；提交前信息模板（型号、版本、日志） | | 术语表（中英） | 统一语言 | 术语中文+英文小字；统一定义与示例截图 | | 版本记录与变更说明 | 可追溯 | 记录新增/修改/移除；标注受影响章节与原因 | | 视觉素材规范 | 提高可读性 | 截图尺寸≥1080p；对比≥4.5:1；统一标注颜色与编号 | | 国际化与本地化 | 便于多语言发布 | 文案分离；避免嵌入文字在图片；保留文本层与可替换变量 | | 下载与离线访问 | 保障可用性 | 提供PDF/打印版；二维码直达最新在线版 |

🎯 质量检查清单 ✅ 应包含：

• 文档封面：设备型号、App/固件版本、发布日期、适用地区
• 准备清单：工具/账号/网络要求（含2.4 GHz说明）与预计耗时
• 一步一图的关键任务流程；每步含成功判定与下一步
• 与App完全一致的按钮/页面名称；首次出现附英文小字
• 型号分流与清晰跳转；禁用“通用步骤”覆盖差异
• 最新截图与视频：版本水印、拍摄日期、高清注解、字幕
• 故障排查决策树：可观察指标、阈值、If/Then分支、停止条件
• 错误提示对照：错误文案/编号→原因→解决步骤→何时联系客服
• 安全提示：分级、图标、后果、避免方法，出现在相关步骤前
• 可访问性：颜色对比≥4.5:1、图示配文字、键盘可达（网页）、替代文本
• 一致的数字与单位；时间/次数/距离给出具体值
• 每节结尾：FAQ（按发生率排序）+ 客服入口与工单信息模板
• 链接与二维码：有效、描述清晰（非“点击这里”），短链与二维码并存
• 版本记录：变更点、受影响章节、回滚说明
• 隐私与安全：不暴露个人信息；掩码Wi‑Fi与账号
• 反馈入口：页面“这页是否有用？”与改进建议收集

❌ 应避免：

• 混写不同型号步骤或界面；用“适用于大多数型号”代替明确分流
• 使用不一致或口语化按钮名（如把“配对”写成“绑定”）
• 只描述现象不提供步骤与判定标准的排障
• 使用过期或模糊截图；图中出现旧版本号或与App不一致
• 依赖颜色作为唯一提示；没有文字说明
• 长段落与被动语态堆积；一句包含多个动作
• 使用内部术语或缩略语未解释（如AP、RSSI无定义）
• 含糊的时间、数量（如“稍等片刻”“多试几次”）
• 安全风险不提示或后果不明确；遗漏断电/断网警示
• 使用“点击这里”作为链接文字；失效链接或跳到首页
• 未标注2.4 GHz限制与路由器设置要求
• 截图中暴露个人信息、SSID或二维码可识别数据
• 在关键流程中插入营销信息干扰任务完成
• 没有版本与变更记录，无法追溯更新来源

提示：为解决“配网步骤与App界面不一致、截图老旧、故障排查无判定、多型号混写”等痛点，务必建立发布前的UI核对与截图更新流程：设计/产品确认UI冻结 → 文案匹配核对清单 → 截图批量更新与版本水印 → 走查型号分流与排障决策树 → 可访问性与链接检查 → 试读测试（非技术用户3人）→ 上线。

📝 核心原则

• 原则：以决策与审计为中心 描述：围绕“业务目标—架构决策—权衡—风险—度量”组织内容，形成从决策到证据的可追溯链路，便于审计与复盘。 优先级：5

• 原则：可复现、可验证的数据与方法 描述：所有性能与可靠性结论必须附方法、参数、环境与数据源，保证任何评审者可独立重现并核验。 优先级：5

• 原则：面向决策者的先结论（BLUF） 描述：先给出结论与影响，再展开证据与推理，突出对成本、风险、合规的直接影响。 优先级：5

• 原则：结构化与可导航 描述：使用固定章节结构、清晰标题、索引与交叉引用；重要信息以表格、要点呈现，降低阅读成本。 优先级：4

• 原则：术语与图例一致性 描述：统一术语表、图标库与配色方案；每张图都有图例、编号与说明，避免名词和图形歧义。 优先级：4

• 原则：合规映射与证据闭环 描述：将监管条款逐条映射到控制、流程与证据，形成覆盖度、有效性、责任人的闭环管理。 优先级：5

• 原则：数据驱动的权衡与边界条件 描述：权衡必须量化（延迟、吞吐、RTO/RPO、成本），明确适用范围、假设与不适用场景。 优先级：4

• 原则：版本化与单一事实来源（SSOT） 描述：采用语义化版本，变更受控；引用代码/配置使用不可变引用（tag/commit SHA），确保一致性。 优先级：4

• 原则：简洁优先，逐层展开 描述：主文只保留决策所需的最小充分信息，细节放入附录/引用，保障快读与深读两种路径。 优先级：3

• 原则：风险-控制-度量联动 描述：每个高风险都要映射到具体控制与监测指标，并有验证频率与触发阈值。 优先级：4

✍️ 写作风格指南

• 指南：先结论后证据（BLUF） 示例：结论：选用Kafka+CQRS满足T+0撮合与审计追溯；在3AZ部署下P99延迟195ms，满足SLO 200ms。证据：见§7性能结果与§9合规映射。 注意事项：每节开头提供1–3行结论摘要；避免把结论埋在段尾。

• 指南：用ADR记录关键架构决策 示例：ADR-2025-004 主题：交易流水存储选型（TiDB vs. PostgreSQL）；状态：Accepted；决策：TiDB；依据：水平扩展与强一致；权衡：写放大与成本增加；影响：备份窗口+15%；链接：基准测试与变更评审。 注意事项：每个ADR必须有ID、状态、日期、决策、备选、权衡、影响、证据链接。

• 指南：量化非功能指标与边界条件 示例：SLO：99.95% 订单入账延迟≤200ms；观测：Prometheus直方图，窗口30天；置信区间：95%；例外：交易开盘前后峰值10分钟不计入SLO。 注意事项：写清测量方法、统计口径和例外窗口；避免“高性能”“低延迟”等模糊词。

• 指南：标准化性能与可靠性呈现 示例：图表包含：硬件/云规格、镜像Digest、工作负载模型（到达分布、消息大小、并发数）、随机种子、采样区间、误差线（±95%CI）。 注意事项：图不超过4种颜色；必须有坐标单位与零基线说明；提供原始数据链接与重现实验脚本。

• 指南：合规映射矩阵写法 示例：条款ID：Reg SCI 1001(a)；控制：自动化变更审批+回滚；证据：变更单#8421、Git tag v2.4.1、回滚演练记录；责任：变更经理；频率：每季度。 注意事项：一条条款可对应多控制；显式标记“部分符合/不适用/待改进”。

• 指南：统一术语与命名 示例：采用“报单（Order）/成交通知（Execution Report）”作为规范术语；非规范同义词在术语表建立映射。 注意事项：首次出现术语用中英文+定义；避免中英夹杂的变体。

• 指南：图示规范 示例：使用统一图标库（系统/队列/数据库/人/外部监管），配色：主色#0B5FFF，警示色#D92D20；每图包含图号、标题、图例、数据流方向箭头。 注意事项：为图表添加替代文本；保证色弱可读（对比度≥4.5:1）。

• 指南：风险与权衡表达模板 示例：选项A（优：低延迟；缺：成本高）；风险：跨AZ网络抖动；缓解：就近路由+限流；残余风险：中；指示器：跨AZ RTT P99>3ms。 注意事项：避免“可接受”这类主观评语，使用定量阈值。

• 指南：引用与证据管理 示例：引用标准用GB/T 7714-2015；代码/配置引用附commit SHA；外链提供快照（存证）与访问日期。 注意事项：避免引用易失链接（会议记录、个人网盘）；必要时存档到受控仓库。

• 指南：变更与版本叙述 示例：版本：v2.3.0（feat：新增隔离级别；fix：修复幂等重试）；迁移影响：数据库schema v12→v13，需10分钟维护窗口；回滚步骤：见附录B。 注意事项：每次发布更新“变更影响”和“回滚策略”，并在文首标注兼容性破坏。

• 指南：用表格/列表替代长段 示例：用“需求—度量—验证方法”三列表描述非功能需求；用“条款—控制—证据—责任—频率”描述合规。 注意事项：表格首列尽量使用可唯一检索的ID（如 REQ-007、CTRL-015）。

🔧 文档结构 | 元素 | 目的 | 最佳实践 | |------|------|-----------| | 封面与版本 | 标识文档与变更状态 | 标题、文档ID、语义化版本、机密级别、作者/审批人、发布日期、审阅周期 | | 扼要（1页） | 面向管理者的决策概览 | 业务目标、关键决策、主要风险与缓解、是否满足监管、核心指标达成情况 | | 读者与范围 | 明确对象与边界 | 目标读者（CTO/审计/安全）、在/不在范围、依赖与假设 | | 背景与业务动因 | 连接业务目标与技术问题 | 用数据描述痛点与目标KPI；列出约束（合规、成本、时限） | | 需求与约束 | 明确功能/非功能与合规 | REQ清单（ID化）；性能/可靠性/安全/隐私与监管条款列表 | | 架构概览图 | 提供系统鸟瞰 | 统一图标+配色；标注数据流、边界、责任域；附图例与编号 | | ADR索引 | 汇总关键决策 | 按时间/主题索引；每条链接到完整ADR；状态（Accepted/Rejected/Superseded） | | 决策与权衡 | 展示选择理由 | 选项对比表（指标、成本、风险）；选择依据与不适用条件 | | 风险登记簿 | 管理不确定性 | 风险ID、影响/概率、阈值指示器、责任人、缓解/应对、残余风险 | | 合规映射矩阵 | 满足审计追溯 | 条款ID→控制→证据→责任→频率→状态（符合/部分/待改进） | | 安全与威胁模型 | 系统性安全分析 | STRIDE/ATT&CK覆盖；数据分类与最小权限；滥用场景与缓解 | | 性能与容量方法 | 定义测试可复现性 | 工作负载模型、环境规格、数据集与随机种子、采样与统计方法、工具版本 | | 基准与结果 | 呈现量化证据 | 表/图标准化；P50/P90/P99、误差线、置信区间；原始数据与脚本链接 | | 可靠性工程 | SLO/SLI与混沌 | SLO定义、SLI采集、错误预算策略；故障注入实验与结果 | | 数据治理与审计轨迹 | 金融合规要求 | 数据血缘、留存策略、不可抵赖审计日志、访问控制与分离职责 | | 运维与变更管理 | 保证可控演进 | 发布流程、审批与回滚、配置管理、不可变制品、运行书（Runbook） | | RACI职责矩阵 | 明确角色与责任 | 关键活动与R/A/C/I标注；与合规控制对齐 | | 术语表与命名规范 | 降低歧义 | 业务/技术术语定义与中英对照；缩写表；命名规则 | | 参考与证据仓库 | 统一事实来源 | 标准/论文/法规引用；代码/配置仓库、测评报告、审计证据链接 | | 复现包说明 | 快速重现实验 | 容器镜像Digest、配置文件、Makefile/脚本、一步启动说明 | | 版本与变更日志 | 追踪演进 | 变更列表、破坏性变更标记、影响评估、兼容性与迁移指南 | | 附录（模板/清单） | 深入细节 | ADR模板、合规检查表、图标库、图表样式、风险评估表 |

🎯 质量检查清单 ✅ 应包含：

• 扉页元数据（文档ID、版本、审批人、审阅日期、密级）
• 1页扼要：关键结论、指标达成、风险与应对、合规状态
• ADR索引与每条ADR的证据链接（测试、评审、PoC）
• 需求-控制-测试-证据的端到端可追溯矩阵
• 明确的SLO/SLI与观测方法（窗口、分位点、置信区间）
• 性能方法学：环境规格、工作负载模型、数据集来源、随机种子、镜像Digest、commit SHA
• 标准化图表：坐标单位、误差线、零基线说明、颜色不超过4种
• 合规映射矩阵：条款ID→控制→证据→责任→频率→状态（含部分符合/不适用的理由）
• 威胁模型与滥用场景、控制有效性验证（渗透/红队/演练记录）
• 风险登记簿：影响×概率评级、触发阈值、负责人、缓解与残余风险
• 版本与变更日志（语义化版本、破坏性变更标记、回滚策略）
• 统一术语表与图例（图标库、配色、连线语义）
• RACI矩阵与审批记录（合规、架构、安全多方会签）
• 证据仓库链接（受控存储）：标准/合规条款、测试数据、报告、日志存档
• 复现包与一键执行脚本（Makefile/Container/CI Pipeline）
• 可访问性：图表替代文本、标题层级清晰、书签与目录
• 法规覆盖声明：覆盖范围、缺口清单与整改计划（含ETA）
• 发布准备就绪核对（运行手册、监控/告警看板链接、容量阈值）
• 数据治理：数据血缘、留存/擦除策略、审计日志不可抵赖与保管周期
• 保密与合规标注：客户数据与PII处理说明、脱敏策略

❌ 应避免：

• 仅有会议幻灯截图、无结构化决策与权衡记录
• 使用“高/低/快/慢/稳定”等未量化表述
• 绝对化夸大（如“零风险”“无限扩展”）
• 缺失单位或统计口径（ms vs 秒；均值 vs P99）
• 图表无坐标/无误差线/颜色过多或对比度不足
• 依赖不可持久的证据链接（临时分享、个人网盘）
• 术语与图例不一致（同一概念多名词、图中无图例）
• 合规“打钩式”陈述，无控制有效性或证据
• 未说明假设与不适用条件，导致结论外推
• 将PoC结果直接等同生产结论，缺少环境差异说明
• 版本号与内容不匹配，变更日志缺失或不完整
• 使用截图替代文本/代码/配置（不可检索/不可复现）
• 表述依赖个人经验或口头共识，无文档化依据
• 未标注机密级别或包含敏感数据（PII/密钥）泄漏风险
• 决策埋在长段落中，无节首结论或索引
• 风险评级主观化，无量化阈值与监测指标
• 规范引用缺失（未给出法规条款ID、标准编号、访问日期）
• 未提供回滚策略与影响评估的变更发布说明

以上指南专为金融级云原生交易系统与合规治理场景设计，兼顾技术决策效率与审计可追溯性，可直接作为白皮书、技术报告与系统架构文档的撰写模板与评审基线。