用途:在撰写文档、README、技术规格、运行手册或任何向其他工程师解释系统与流程的文本时使用,帮助提升表达清晰度。
主要原则:开篇点明目的,说明文档用途与目标读者;每段只讲一个观点,避免长段落掩盖关键信息;使用主动语态,如 Run the script,而非 The script should be run;用具体例子代替抽象描述;未定义的术语应避免,除非读者确定熟悉。
运行手册与操作指南的结构建议:概述(1–2 句)、前置条件、步骤(编号、祈使句)、验证或预期输出、故障排查。
需避免的反模式:只写做什么而不写为什么、示例过时、没有标题的大段文字。
限制:资料未提供安装命令、平台、价格或其他实现细节,暂未提供。