技术写作与设计评审¶
工程文档的任务是帮助读者做决定、复现实验或安全地操作系统。装饰性术语不能替代清楚的需求、证据和限制。先确定读者要完成的动作，再选择报告、设计说明或操作规程的结构。
目的与学习成果¶
- 将需求写成带单位、容差和验收方法的可测试陈述；
- 区分观察、计算、推断、决定和待办；
- 让图、表、公式和引用可以独立理解与追踪；
- 记录备选方案、权衡、风险与停止条件；
- 通过同伴评审发现歧义和不可复现步骤。
最小环境¶
- 支持标题、链接、代码和图表引用的文本格式；
- 版本控制与拼写/链接检查；
- 一个已有的安全低风险实验或设计；
- 可生成 PDF 或静态网页的路径，但源文本保持可审阅。
记录构建工具与模板版本。字体和排版不是核心证据；发布格式必须保留可复制文本、可导航标题和图片替代说明。
学习顺序¶
- 读者与动作：写出读者是谁、要决定什么、已有背景和成功标准。
- 结论先行：先给结论与适用范围，再展开方法和证据。
- 需求表述：每条需求包含对象、条件、阈值、单位和验证方法。
- 证据组织：图表紧邻解释，标题写明对象与条件，引用指向原始来源。
- 决策记录：列备选、权衡、风险、假设和为何选择当前方案。
- 可执行评审：让评审者按文档复现一步并记录阻塞点。
验证任务：一页设计评审¶
从已完成的小信号滤波器或数字模块中选一个：
- 写一句问题、三条可测试需求和一个非目标；
- 用一张带单位图和一张紧凑结果表支持结论；
- 链接原始数据、生成命令与设计版本；
- 比较两个方案，说明选择、成本和残余风险；
- 写出一个会推翻当前结论的测试；
- 请另一位学习者只读文档执行验证，并修复一个歧义。
验收要求读者无需口头补充即可找到输入、运行命令、预期结果和失败处理。
常见失败与排查¶
- 开头只有背景没有结论：把决定、范围和关键数值放在首段。
- 需求写成“性能良好”：补充指标、条件、阈值、单位和验证方式。
- 图表离开正文无法理解：补充标题、图例、数据来源和文字结论。
- 精度看似很高：按测量/模型不确定度限制有效数字。
- 步骤靠“显然”跳过：让陌生读者实际执行，记录每个隐含前提。
- 文档与实现漂移：让参数和图由同一权威源生成，并在 CI 检查。
可复现证据¶
- 文档源文件、构建命令和发布产物；
- 读者、目的、范围和术语定义；
- 需求到测试的追踪关系；
- 图表的数据 ID、脚本、参数和版本；
- 引用的稳定标识与访问日期；
- 备选方案、决定、风险和未决问题；
- 评审意见、处置结果和变更记录。
成本、许可与无障碍¶
文本工作流可以完全使用自由工具。模板、字体、图标、图片和引用材料均需检查许可；可引用不代表可复制全文。提供开放格式或网页，避免读者必须购买编辑软件。
使用语义标题、清晰链接文字、足够对比度和图片替代说明。不要只用颜色、位置或“见上图”表达关系。公式给变量定义，表格避免过宽，视频演示附文字步骤。
安全边界¶
- 操作说明必须写额定值、前置检查、停止条件和故障安全态；
- 不发布密钥、个人数据、受控硬件细节或未协调漏洞；
- 不用文档替代机构培训、制造商手册或合格监督；
- 高能量步骤必须由具备资格的评审者审核；
- 证据不足时写“未验证”，不能用确定语气填补空白。
完成清单¶
- 读者、动作、范围和非目标明确。
- 每条需求都有条件、阈值、单位与验证方法。
- 结论与关键限制在开头可见。
- 图表可追踪、可访问且有文字解释。
- 事实、推断、决定和待办分开。
- 构建与复现步骤经陌生读者试走。
- 许可、隐私与安全审查已完成。
- 评审意见及处置保存在版本历史中。