用途:创建或编辑通用、产品、API 及技术文档,让定义明确的读者能理解、决策、开始操作或从错误中恢复,并避免空泛的 AI 式行文。
模式选择:动笔前先确定文档模式,不要混用。帮助人理解、决策或恢复,用 STE 风格的 human-friendly.md;需要精确核对的步骤、需求、接口或配置,用严格模式的 technical-precision.md;两者都要时用分层写法,先写面向人的指南,再把每个精确主张、schema、端点或步骤链接到技术参考。
工作流程:识别读者、其当下问题、环境与出错后果,只追问会改变答案的缺失事实;确定模式与输出契约,包括读者应执行的动作或决策、所需证据、事实来源及必要的负责人、日期、版本;清点主张,区分事实、假设、示例、建议与未决项,不得悄悄升级;结构应让读者在问题被回答后即可停止阅读,标题描述答案或任务而非写作过程;用具体语言起草,给出条件、动作、可观察结果与恢复路径;按选定模式的规则编辑。
编辑规则:保留含义、范围、约束与不确定性;用具体名词和动词,指明行为者、对象、条件与结果;答案、动作或决策前置;删除清嗓、自夸、填充过渡与无法证实的全面性声明;用可执行示例替代泛化示例,并标注前提、输入、输出与预期结果;不靠强加个性或随意变化来“去 AI 化”,而是提升有用性;保持并列项真正并列;谨慎使用 MUST、MUST NOT、SHOULD、MAY,区分无必要时用直接平实的英语;lint 提示仅作复查触发,若修改会降低准确性、可用性或违背受控术语,可有意识地保留例外。
来源与变更:对可争议、代价高、易变或与安全相关的事实引用权威来源;给出版本、日期、适用范围与配置边界;未知事实应说明未知及下一步验证方式,不得用貌似合理的语言填补;同一规则或步骤保留唯一标准表述,复用或引用而非制造近似重复。
交付前自检:预期读者能否不读全文就找到任务或决策;每条实质主张是否有来源、测试、有界假设或被删除;读者能否按所述前提与步骤复现承诺结果;警告、失败场景、限制、版本约束与恢复操作是否在需要处可见;每句话是否都改变读者的理解或行动。
使用方式与限制:对 Markdown 或纯文本可运行 python3 scripts/ste_lint.py --mode flavored draft.md,步骤类文档用 --mode strict,检查项与局限见 linting.md。如需 STE 风格文档的读者顺序、结构与示例见 human-friendly.md;严格流程见 technical-precision.md;S1000D 与 ASD-STE100 的研究依据与合规边界见 s1000d-research-basis.md。除非所要求的标准、版本、项目规则与验证工具齐备,不得声称符合 S1000D、ASD-STE100 或 ATA iSpec 2200。资料未提供具体功能细节、收费、价格与平台支持信息。