teaching-notes-writing

教学笔记写作

这是一项可移植的写作技能：可独立使用，也可由 openpress-create-pages 在页面内容面向学习者、属于教学材料（讲义、练习册、学习指南、教程章节）时加载。openpress-create-pages 负责触发条件和冲突解决规则。

教学笔记面向仍在建立心智模型的学习者。这项技能提供建议的内容框架、讲解策略、示例、练习思路和答案安排指导，但不强制采用某一种固定的章节模板。

职责

• 从学习者可能已有的心智模型出发。
• 先比较相近的概念，再介绍正式规则。
• 逐步展示操作过程，并呈现清晰可见的状态变化。
• 用文字说明原因、警告和解读，避免图示承载过多信息。
• 建议与章节内容相匹配的练习形式。
• 让学习者有机会尝试后再给出答案。
• 建议何时应将结构、关系或状态变化转化为图示；实际的图示语义由 openpress-diagram-drawing 负责。

边界

• openpress-create-pages 负责基于页面的产物的公开内容规范，以及 H1/H2/H3/H4 结构。
• openpress-diagram-drawing 负责图示语义。
• openpress-create-pages 负责页面视觉风格和组件实现。
• openpress 负责 CLI、验证／导出／渲染命令，以及源文件与生成文件的边界。
• 这项技能仅负责面向学习者的讲解建议和练习设计模式。

建议框架

将其作为起始框架，而非必需模板：

1. 从学习者遇到的具体问题或困惑出发。
2. 比较相近的概念、状态或表示形式。
3. 逐步展示操作或想法。
4. 适当时加入一个简短的检查、跟踪或练习任务。
5. 让学习者有机会尝试后再给出完整答案。

如果概念依赖空间结构、归属关系、箭头、状态转换或前后关系，请将视觉语义交由 openpress-diagram-drawing 处理。

面向学习者的界限

渲染后的教学页面应面向学习者，而非教师或 Agent。

• 不要包含仅供教师查看的提醒、制作说明、内部理由或入门技能说明。
• 将内部规则保留在技能、设计文档或源文件参考中。
• 在正文、图示、表格和代码中使用一致的术语和变量名。

何时阅读参考资料

• 有关对比写作、讲解顺序、练习题类型和答案安排，请阅读 references/teaching-patterns.md。
• 在讲解代码、伪代码、数据结构、指针图示、内存状态或程序跟踪时，请阅读 references/programming.md。