用途:起草、改写或审计模块化企业技术文档,让前置条件、系统状态、操作步骤和验证结果都明确可查。
主要能力:保持产品名称、版本、命令、文件、路径、选项、界面标签和支持配置的精确性;不把经过测试的配置泛化为通用支持;区分必需、推荐、可选、已弃用和不支持的行为;在缺少权限、平台、版本和持久化信息时主动询问。
模块化写作:一次只构建一个模块,选择单一主导类型——概念(提供后续决策所需的心智模型与关系)、过程(说明前置条件,执行一个目标导向的操作序列并验证)、参考(以一致的查阅形式呈现事实、选项、语法或限制)、故障排除(识别症状、诊断证据、原因与恢复方法)。不要在一个过程中混合多个独立目标;当工作流需要多个目标时,把模块链接成更大的组合。
写作风格:仅在读者执行动作时用“你”称呼;系统或组件执行动作时直接点名。优先使用主动语态和具体动词,避免把动作藏在抽象名词里。术语保持稳定,与权威产品的首字母大小写一致。读者必须先检查的条件放在指令之前。说明作用范围:主机、集群、命名空间、用户、服务、会话或持久化配置。使用字面、全球可理解的语言,定义不熟悉的缩写。陈述安全与数据后果,不危言耸听也不委婉。
过程写法:用一句话给出目标;列出前置条件、权限和起始状态;每步以祈使动词开头,每步只保留一个主要动作;原样展示命令和配置,解释占位符与变量;在有助于读者安全继续时说明预期结果;添加带可观察成功条件的验证部分;当变更具有持久性或风险时,添加回滚、清理或恢复。
应避免:无清晰边界地混合概念、过程和参考内容;作用域内有多个组件或文件时使用模糊代词;拟人化、习语、营销语言和装饰性文字;没有证据的难度判断和安抚性断言;未解释的 root 权限、环境变量、路径或重启要求;包含真实凭据或不安全默认值的示例;没有明确作用域的支持或兼容性声明。
最终检查:核对模块化、前置条件、平台与版本作用域、命令准确性、可观察结果、安全影响和恢复。删除无助于读者决策或完成模块目标的背景内容。仅在来源、署名、许可或维护问题方面阅读 references/provenance.md。
限制:资料未提供具体安装命令、收费方式、平台支持范围或效果数据。