technical-book-lab-design

技术书籍实验设计

核心视角

技术书籍实验不是一堆命令，而是引导读者完成转变的过程，具有明确的起始状态、安全路径、可见进度、预期输出和退出标准。读者应知道自己构建了什么、它为何有效、如何验证，以及失败时该怎么做。

使用此技能来设计或改进：

• 自托管章节。
• DevOps、基础设施、编程、数据或安全教程。
• 演示示例和练习。
• 实验的前置条件和环境假设。
• 检查点、预期输出和故障排查分支。

参考资料导航

需求	阅读
核心实验概念和术语	references/core/knowledge.md
实验设计规则	references/core/rules.md
前后对比示例	references/core/examples.md
实验审查清单	references/core/checklist.md
逐步设计实验	workflows/design-runnable-lab.md

工作流

1. 明确读者成果

说明读者完成实验后将能够执行、决定、部署、调试或解释什么。

如果成果只是“了解 X”，就进一步明确，直到能以可见成果证明进展。

2. 明确起始状态

列出读者已经具备的条件和知识：

• 必需概念。
• 账户、硬件、软件、版本和操作系统。
• 网络、域名、DNS、权限、凭据或安全限制。
• 文件或代码仓库状态。

将缺失的前置条件提前处理、精简，或链接到配套材料。

3. 设计路径

将实验安排为一系列小型检查点：

• 在每项操作前说明其目的。
• 给出最小且安全的命令或改动。
• 展示预期输出或状态。
• 添加快速验证步骤。
• 说明接下来的决策。

4. 添加故障处理

技术读者不只需要顺利完成的路径。

• 列出可能出现的错误及其含义。
• 对有风险的改动添加回滚或清理步骤。
• 标明会暴露服务、更改权限、产生费用或影响数据的步骤。
• 告诉读者何时应停止并寻求帮助。

5. 完成闭环

每个实验都应以以下内容收尾：

• 最终验证。
• 读者现在应理解的内容。
• 他们接下来可以安全修改的内容。
• 清理、维护或安全后续事项。

输出格式

设计或审查实验时，返回：

1. 读者成果和起始状态假设。
2. 包含检查点的实验顺序。
3. 预期输出和验证步骤。
4. 故障排查表。
5. 安全说明和清理步骤。
6. 建议的配套资源或前置条件。

质量标准

让实验对真实环境中的真实读者确实有用。相比抽象解释或未经测试的命令序列，应优先提供具体输出、检查点和故障处理。