维护清晰且可验证的文档

新增或修改页面时,遵守内容与图示标准和五类页面模板。保留一份权威合同与一份正文源。当前实现、目标设计与精确参考配置分别表达。

围绕读者任务写作

开头说明结果、前提与限制。解释谁在什么上下文中处理什么输入,以及可以观察到什么结果或失败。使用稳定术语和明确单位。原始摘要/日志保存在证据链接中,不打断操作主线。不得用“完整支持”等结论替代明确范围。

教程提供完整维护夹具或固定版本外部消费工程,以及实际命令、预期结果和清理步骤。源码拥有的输入使用 literalinclude。片段必须说明不完整原因。普通文档构建不执行任意 Markdown 命令、不获取 latest 示例,也不操作硬件。

审查图示与翻译

图示具有 ID、范围、caption、alt、可编辑源和本地 SVG。标明箭头含义、可选路径、所有者与失败责任。对照实际代码/合同审查,再渲染并检查文字、交叉线、放大、打印和离线资源。渲染成功本身不证明语义正确。

英文正文通过 gettext PO 提供中文;中文合同保留其原文语言。翻译绑定实际正文摘要、实际提取消息和独立审查。源变化、fuzzy 或消息缺失时,显示真实状态,不能冒充翻译完整。不得翻译 C 符号、配置键、结果码或原始回执。共享术语使用已审查双语术语表;其权威链接维护单一合同。

采用正确验收边界

执行当前 CLI 文档中的统一文档命令。源码检查、严格双语构建、真实配置/消费工程执行、图示审查、离线包和实际站点检查分别建立结果。记录命令退出码与精确输入;不能从本地 HTML 声称部署完成,或从准备计划声称硬件通过。

文档台账维护实现和验证退出条件。迁移映射保留历史路径;旧 API 转向有版本意识的迁移或历史页面,不能静默解释为另一份新函数合同。资格记录保留原路径和身份。