tutorial-authoring

教程编写

在面向学习者的材料中使用此技能：读者会按照说明构建、配置、理解或练习某项内容。

此文件是执行核心。仅在任务需要时加载详细参考资料：

• 研究依据、证据边界和引文： references/research-foundations.md
• 基于动作的指导和无障碍视频： references/video.md
• Course Docs MDX 契约和机械化检查： references/course-docs-platform.md
• 无障碍详情和文本替代模式： references/accessibility.md
• 审阅清单：REVIEW-CHECKLIST.md

范围

默认目标：初级到中级学习者。

教学辅助可能出现专业知识逆转效应：相关先备知识较少的学习者通常会受益于更多指导，而先备知识较多的学习者可能会受到冗余辅助的阻碍。应根据目标学习者和相关策略的证据，调整每种指导形式的程度；不要假设每项多媒体原则都会以完全相同的方式发生逆转。

在作者编写语境或元数据中保留面向作者的受众标签。除非学习者确实需要了解，否则不要在面向学习者的正文中出现「初学者向」之类的措辞。

无论文件类型或路径如何，都应将学习者可见的材料视为教学内容。嵌入在 JSON/YAML/TypeScript 固定数据、Bundle 源码、测试固定数据或生成源码中的提示词、标签、代码上下文、反馈、解释和可见状态文本，接受的作者审阅标准应与教程文档中的正文相同。

教育目的

采用这一规范性目的：学习者以积极的心态享受学习，同时提升实际能力，并运用所学进行思考、创作和自主持续学习。

这是教育体系的价值判断，并非经研究证明的唯一目的。学习科学为实现这一目的的手段、副作用和边界条件提供参考。享受学习不意味着始终轻松；严谨也不要求承受不必要的挫折。在减少意外困难的同时，保留有意义的回忆提取、决策、问题解决和有效的努力。

规则来源

将研究依据与执行严格程度分开处理：

代码	含义
R — 多项研究支持	多项独立研究或研究综述在相关边界条件内支持该方向
S — 多项研究综合	结论依据一条明确的推理链得出，且该推理链只使用多项研究或综述支持的前提
L — 本地决策	规范性目的、写作惯例、产品决策或平台契约；并非科学发现
U — 尚无定论	现有研究无法确定该决策

上述教育目的具有规范性，因此属于本地决策，而非实证结论。只有当证据及其边界条件可在 references/research-foundations.md 中追溯时，规则才能提升为 R 或 S。对于 S，应记录推理链；不要将一项研究结果与未经审查的设计直觉结合。不要仅仅为了填补设计空缺，就把 U 项变成教学规则：应收集更多证据、测试其他方案，或明确将选择保留为本地决策或实验方案。

证据强度和执行严格程度是两个独立维度。严格的平台契约可以是 L；正确应用需要语义判断的 R 原则仍可仅作为建议。

编写流程

创建或审核教程时，请按以下顺序进行。

1. **目的 / 预期成果：**确定学习者应获得什么有价值的能力，以服务于教育目的。
2. **学习者状态：**确定相关的先备知识、先前教学，以及预期时间跨度：初次表现、保持、迁移，或这些目标的组合。
3. **学习单元 + 对齐的证据：**定义要学习的内容，以及哪些可观察证据能够证明预期成果。
4. **学习活动设计：**选择本次的学习体验，包括合适的模式 / 策略和有意义的活动。
5. **适当的辅助：**提供与学习者、表现和目标相匹配的讲解、示范、反馈和补救支持。
6. **投入 / 有意义的挑战：**支持学习意愿和可实现的进步，但不要以轻松程度衡量质量。
7. **学习者主动加工：**设计相关的提取、解释、预测、比较、决策、应用、调试或创作活动。
8. **课程进阶：**如果课程负责规划这一时间跨度，就安排后续练习、提取，以及在条件变化时的迁移。
9. **呈现 / 无障碍性 / 初次阅读体验：**选择呈现形式和组件，然后检查可访问性、清晰度和无意中造成的难度。

学习系统与教程页面

按照“目的 → 单元／预期结果 → 事件／学习者体验 → 证据 → 随时间推进”的思路进行设计。单元是 WHAT，事件是 HOW / NOW，证据是 EVIDENCE，随时间推进是 OVER TIME。页面／章节是该模型之下的呈现／分发选择。组件用于呈现选定的体验；其属性并不决定教学法。章节不会仅仅因为存在，就必须有局部收尾、概念或提示。

在课程层面的设计中，要区分稳定的目标与学习者为实现该目标而参与的每一次活动：

• 学习单元是稳定的学习目标或能力：要学什么。单元可以构成层级，从更广泛的目标延伸到叶节点目标。页面不是学习单元。
• 学习事件是一次以一个或多个学习单元为目标的学习或练习活动：学习者这次如何参与。同一个单元可以在多个事件中反复出现，并采用不同的活动和证据。
• 课程进阶是事件随时间有序地反复出现。规划后续的提取练习与分散练习、累积或混合练习、在内容和目标适用时进行交错练习，以及迁移。这些是有证据支持的设计目标，并非本地综合得出的固定序列，也不应声称其为经研究证明的最佳方案。
• 证据／评估是与学习单元目标相一致、可观察的证据。练习是一种任务或容器格式；它可以是常规练习，也可以用于迁移。迁移证据要求条件有实质性变化，并要求学习者选择或调整已学原理。
• 页面是呈现与分发单元。它可以呈现一个事件的一部分，也可以呈现多个事件的材料；一个事件可以跨越多个页面或其他格式。页面不定义目标或活动。教学通常可以按照学习者可见材料中的事件顺序进行；不要要求重复编写教师教案。

对于初始学习顺序，使用 I-PS（先讲授，再解题）和 PS-I（先解题，再讲授）。这种模式描述的是讲授与解题的顺序，而非整页模板。当有助于落实事件时，可以在兼容的模式中采用更大的策略。生产性失败是 PS-I 的一个特定高保真子集／变体，不是所有 PS-I 的同义词；有意设计的先解题后讲授事件并非无指导的挣扎。探究式学习是一种更广泛的策略，并不意味着无指导的发现。应在有用时区分工作示例、自我解释和提取练习等更小的技巧；不要强加会增加创作负担、却无法改善执行效果的分类体系。

教学目标时限

不要让每个教程都针对同一种结果进行优化。

• **初始表现／工作辅助：**优先考虑在说明可用时快速、准确地完成任务。详细的任务匹配说明或以视觉为主的路径可能是合适的。
• **学习（包括保持）：**应提供随时间提取、解释或复现操作流程的机会，而不是只衡量首次尝试的速度。
• **迁移：**应纳入原理、变化或在条件改变时的应用，确保成功不局限于照搬一种示范流程。

一个教程可以服务于多个目标时限。当目标相互冲突时，不要为了最大化首次完成速度而牺牲明确要求的保持或迁移成果。逐步撤除支持与混合式讲授可以兼顾这些目标。

本技能采用的认知负荷框架

以 Sweller、van Merriënboer 和 Paas（2019）作为操作基准，而非沿用较早的三类负荷加法简述。同时，也要考虑 Kalyuga 和 Plass 于 2025 年提出的目标驱动修订提案：某种认知需求是否有用或多余，可能取决于教学目标、学习者的先验知识、动机和情感状态。应将该提案视为重要扩展，而非已形成定论的共识。

• 内在负荷取决于任务要素之间的相互作用，相对于学习者的专业水平以及当前目标而言的复杂程度。可通过安排学习顺序、在必要时进行预先训练、提供完整示例，以及适当分段来管理。
• 外在负荷源于相对于当前教学目标而言可避免的认知加工。应减少不必要的搜索、注意力分散、无关细节、令人困惑的导航，以及没有明确作用的重复内容。
• 意向性加工并非一种应当最大化的独立第三类负荷。控制可避免的认知需求后，应留出空间，以便进行有益的提取练习、自我解释、练习和反馈。

应减少相对于目标而言可避免的认知加工，让学习者能将认知资源用于与学习相关的思考。提取练习、自我解释、问题解决、选择、调试、调整和迁移都可能是有益的挑战。不要仅仅为了降低学习者报告的努力程度而移除这些活动。

当策略相互冲突时：先明确教学目标，再减少相对于该目标而言可避免的认知加工，管理学习者面对的任务复杂度，然后加入仍适合其可用认知资源、且与学习相关的活动。如果动机和情感状态会实质性影响学习者参与任务的能力或意愿，也应予以考虑。

来源与局限请参阅 references/research-foundations.md。

首选呈现形式

选择能够以最少的可避免整合工作传达学习者操作的呈现形式，同时支持预期的教学范围。图像是一种选择，而非默认选项。

任务	常用的首选呈现形式
空间化的 UI 路径、布局或视觉关系	带注释的视觉内容
编写或修改代码	代码 / CodePreview
简短的非空间命令或设置	文本
结构关系或状态流转	图表
动作、时序或连续变化是教学重点	支持时使用视频 / 动画；请参阅 references/video.md

辅助呈现形式应补充互补信息：精确的输入值、悬停与点击的区别、因用户而异的路径、将文字说明与视觉内容对应起来的标签，或仅靠形状无法表达的语义。

不要通过两种同等醒目的路径，重复呈现同一套完整操作步骤。在两种形式中都可以出现简短的辨识线索、标签、数字和位置锚点，只要这些内容能减少搜索或对应所需的认知成本。

**无障碍等效内容并非无谓冗余。**如果视觉内容承载了关键信息，就应提供等效的文本路径。应优先采用这样的呈现方式：辅助技术可以访问等效内容，或学习者可以按需获取，同时又不强迫所有学习者都处理两套完整的平行步骤。

操作单元

将一次操作视为一个连贯的学习者操作过程：围绕一个即时子目标而进行、在局部上统一的操作或简短序列。它不一定只包含一次鼠标点击。

例如，以视觉为主的操作可以合理地展示一段简短的导航序列，如点击 → 打开菜单 → 将鼠标悬停在子菜单上 → 选择项目，前提是整个序列构成一个连贯的操作过程。

如果拆分操作能形成有意义的状态／子目标边界、降低整合成本，或让恢复／验证更清晰，就应拆分。不要机械地按字段、点击或编号标注拆分。

整个操作必须让学习者无需猜测即可采取行动。对于以视觉为主的操作，可见文字可以只提供补充信息，而不必复述完整的视觉路径。对于必要的视觉指令，应保留完整且易于访问的文本等效路径；但如果平台能够通过程序化方式或按需呈现该路径，就不要让它在视觉上与主要路径争夺注意力。

不要为了“修正”重复信息，而留下诸如「点击」这样不明确的指令，导致主要呈现方式及其易于访问的等效内容都没有清楚说明目标和操作。

对于任何需要作出回应的活动，尝试前可见的状态必须明确说明学习者要回应什么、需要采取什么行动或作出什么判断，以及预期的回应形式。不要依赖共享渲染器自行补充作者未写明的特定领域任务含义；只有在不会错误描述任务的情况下，才可以使用中性无障碍标签或平台标签。

分段与注意力分散

使用由学习者掌控的有意义内容块，不要机械地遵循“一屏 = 一段”的规则。

在 GUI 教程中，屏幕／状态转换是有用的边界候选，但语义子目标才是更重要的标准。编码或概念类任务即使没有屏幕转换，也可能需要分段。

应在有意义的语义或因果边界处分段，而不是按屏幕数量分段。如果同时发生的变化会让人难以辨别哪个变化导致了哪个结果，就应将其分开，以便观察各自的作用。当暂时“尚无可见变化”的状态有助于区分不同作用或阐明心理模型时，应保留该状态；例如，先添加 HTML 类，再用 CSS 选择该类。如果机械拆分会增加整合成本，就不要这样做。

有意义的内容段可以逐步展开。当后续理解需要与先前内容进行比较或整合时，应让先前内容保持可见或便于重新打开。面向新手的引导式流程可以引导学习者向前推进，同时让已讲解内容仍可供复习；这并不意味着不受限制的导航总是有益的。在复习前面的步骤时，应尽可能保留学习者的状态和答案；如果预期要重置，应明确说明。学习者提交回应后，如果比较很重要，就应在原处或便于立即比较的呈现方式中保留该回应。除非第二种呈现方式能发挥不同的解释、规范化、比较或无障碍作用，否则不要在已显示正确回应旁边立即添加完全相同的标准答案。累积式呈现是一种有希望且符合证据的候选方案，但尚未被证实为普遍适用或唯一最优的 UI。页面内的累积式复习有助于减轻记忆负担，但不能取代之后的间隔提取练习或迁移练习。 具体使用标签页、折叠面板、内容折叠及布局，仍属于局部／实验性选择。当学习者需要快速重新进入内容时，简洁的完成后参考内容可能有所帮助；但并非每个页面都必须提供。

当学习者必须在脑中整合彼此分离的信息来源时，就会发生注意力分散。物理距离是常见原因，但并非定义。应让相互对应的视觉内容、标签、数值和说明文字足够接近，以便学习者无需进行不必要的查找即可整合。

概念与预先教学

概念用于提供理解或完成当前或近期学习活动所需的概念性知识。

• 优先在首次使用前介绍概念是一种默认做法，而非唯一的安排要求。对于复杂活动，可以提前进行教学，为学习者做好准备；放在总结、检索或参考内容中，在语义上也可能合适。
• 说明概念是什么，以及它为什么对当前活动很重要；避免介绍与遥远未来无关的内容。
• 需要预先教学时，应教授名称，以及学习者必须在后续任务依赖这些内容前理解的相关特征和关系；仅列出名称无法帮助学习者建立这种理解。
• 根据清晰表达所需的篇幅来写。六个或更多句子可能会触发对概念混杂或参考细节的审查；这既不是硬性限制，也不是研究阈值，内容较短也不一定更好。

如果学习者已经了解该概念，采用可折叠或参考形式，甚至完全不写概念介绍，可能更合适。

面向学习者的引导

如果页面介绍、先修知识提示、目标摘要、章节目标、预览或顺序说明能为学习者理解当前活动、结构或当下的决策提供具体帮助，就应采用。进行冷读审查时，考虑修改那些只是重复标题或相邻正文、保证课程顺序、标准单元目标，或学习者尚无法运用的信息的内容。这项 L 审查惯例并不否定学习目标或先行组织者；当它们有助于引导注意力或展示结构时，可以发挥作用。 参见 references/research-foundations.md。

陌生术语可以先出现在引导内容或标题中，再进行解释。如果学习者需要知道术语的含义才能理解或采取行动，就应先说明名称及相关特征或关系，再依赖学习者对其形成理解；仅预告名称不能算作预先教学。如果先修知识提示能帮助学习者采取行动进行准备、重新进入学习或恢复进度，就很有用。在顺序固定的线性学习过程中，如果提示没有带来这类价值，就可以省略；先备知识固然重要，但不意味着每一页都必须设置先修知识界面。

对于课程文档，应将学习者行动一致性作为一项 S 类研究综合结论：面向学习者的标题、紧接其后的说明、任务描述和相关界面提示，都应传达同一阶段要求采取的行动。如果不一致导致学习者不清楚自己是该查看、书写、选择、修正、尝试、检查、回答还是创建，就应将其视为面向学习者的缺陷。只要表达的是同一行动，自然的改述没有问题；不要求措辞完全相同。如果行动有多个，只要顺序明确且每个阶段都清楚，就没有问题。这项综合结论结合了有关标题与信号、连贯性以及任务行动映射一致性的证据；它并非针对特定动词组合直接验证的规则。参见 references/research-foundations.md。

还应单独审查相邻内容之间的顺序／话语连贯性：学习者当前所处的状态，是否让他们清楚为什么下一个主题、操作或概念此时会出现？这比检查标题与活动是否要求同一行动更广泛。对于面向新手的初始教学，这项审查尤其有用。简短的过渡可以连接学习者的目标、观察到的结果、当前方法的局限、对下一概念或操作的需求，或明确的内容转换。不要让学习者自行推断材料可以简要说明的逻辑联系。冷读审查时可思考：

• 刚读完前面的内容后，学习者会不会问“为什么现在讲这个？”
• 新概念、工具或操作是否在其必要性变得明确后才出现？
• 标题是否揭示了超出学习者当前认知阶段的结论？
• 将前一结果与下一段解释或操作联系起来的目的或原因，读起来是否自然？ 将此视为一项 S 研究综合，而不是要求在每个段落之间添加过渡，或让内容对所有受众都尽可能连贯。保留检索和问题解决活动中有意设置的推断；不要将高度连贯设为已有大量相关知识的学习者的普遍规则。

对于新手的初始教学，句子通常应能根据截至该处已介绍的信息加以理解；不要让后续内容成为理解前面句子的必要条件。如果符合课程的因果结构，优先采用当前／已知状态 → 需求／问题 → 新概念 → 应用的顺序。这一顺序是局部启发式，并非普遍最优的顺序。稳定的名称或标识符（例如，index.html、style.css 或浏览器结果）属于 L 可用性／无障碍惯例；当响应式布局可能移动目标时，它们比仅以视口相关位置作为参照更可靠。如果能直接说明学习者的操作，就优先采用直接的任务表述，而不是撰写说明／元标签。

面向学习者的提示应在提出问题时明确说明所问的对象或内容、需要作出的判断／执行的操作，以及预期的回答形式。除非指代对象或基准已明确无误，否则不要让学习者自行推断。选项应自然地补全或回答题干；避免让日语措辞成为需要单独解码的任务，也不要预设答案所属的类别。保留首次尝试前预期的检索或生成过程。对于 Course Docs，精确核对日文文案是局部质量综合，并非普遍适用的研究定律。如果要将填空题的回答返回供比较，优先展示完整的语义句；这是范围有限的局部惯例，并非经过直接测试的普遍规则。

保留理解主要教学路径、后续操作或该路径上 QuickCheck 所必需的解释；不要只依赖提示、折叠内容或可选说明框来呈现关键原则。如果相互依赖的操作、结果、代码和解释必须整合在一起，应将它们放得足够近，以避免不必要的查找或注意力分散。不要根据示例学习、邻近性或连贯性研究推断固定的教学顺序；应根据实际目标和学习者状态选择 Event 模式和活动顺序。

激活

如果存在有用的先验知识锚点，可通过回忆、比较、先前课程／任务或恰当的类比来激活它。

不要仅为满足检查清单而生造类比。激活是唤起已有知识；预训练则是教授尚未掌握的知识。

脚手架与逐步独立

目标是提供适当的帮助，而不是尽量减少指导。独立性提升是能力发展的结果，而不是拒绝提供有用帮助的要求。

对于相关先前知识较少或未知的学习者，默认在要求其进行大量独立构建前，提供足够的示范或引导支持。此默认做法并不排除在适当情况下采用高保真、有支持的 Productive Failure PS-I 设计：经过刻意设计的先解决问题、后进行讲解，并非无指导的挣扎。边界条件请参见 references/research-foundations.md。

根据先前知识和学习者表现，逐步撤除、保留或恢复支持。不要使用固定阈值，例如“第二次出现就引导”“第三次出现就独立完成”。

根据对目标学习者的已有了解和观察到的表现来调整帮助；个性化的自适应掌握度跟踪属于未来范围，并非此技能的必需实现。

适用时，可采用以下递进方式：

• **示范示例：**提供必要指导的完整示范。
• **引导式变式／补全：**由学习者做出选定的决策。
• **独立应用：**学习者自行规划或迁移应用，不提供操作步骤指引。

并非每个页面都需要包含全部三个阶段。先前知识扎实的学习者可以从递进过程中的较后阶段开始。

参与度、愉悦感与自主性

在有助于实现学习成果时，可考虑真实相关性、有意义的挑战、可见的进步、支持胜任感的反馈、有意义的选择、学习者控制权和积极参与。这些是设计选项，并非每个页面都必须纳入的清单。不要凭空制造相关性，也不要把选择本身当作目的。愉悦 ≠ 轻松；严谨 ≠ 不必要的挫败。

同时评估学习成效与体验：流畅愉快的学习过程或“正在学到东西”的感觉，本身并不能证明能力有所提升；而有益的努力也可能让人觉得困难。应结合适当的证据与学习者反馈。

练习、提取、反馈与对齐的证据

实质性的学习目标应有与该目标及预期教学时间跨度相适应的证据。

目标／证据需求	可用的证据形式
可观察的行为或状态	Verify
提取／理解	QuickCheck
构成一个里程碑的多个可观察条件	Checkpoint
应用或迁移任务	Exercise

此映射是用于选择证据形式的质量惯例，而非局部于 Section 的结束要求。应在递进过程中的适当节点，将证据与 Units 和 Events 对齐，而不是给每个 Section 都添加检查。

生成性活动会明确要求学习者进行选择、组织、整合、提取、解释、预测、比较、应用、调试、调整或创作。QuickChecks、自我解释和设计得当的 Exercises 都可承担此类作用。被动的 Verify 可能提供有价值的反馈，但不属于生成性活动。

有效的验证不应只是复述界面状态。如果某项回应可以客观评分或核验，且验证能消除学习者的不确定性，即使结果也已可见，仍应保留此表现反馈；不要将其作为“冗余复述”删除。如果纠正性或解释性信息会有所帮助，仅靠验证并不充分：应根据情况，将反馈与实际结果、正确信息、因果解释或逐步有用的提示联系起来。如果展开说明会有所帮助，就不应让仅说明正误的反馈结束整个反馈循环。

补救属于错误支持，而非目标证据。并非每个工作指南或仅针对初始表现的页面都必须包含主动／生成性活动。

立即成功是初始表现的证据，并非持久学习或迁移能力的证明。只要课程范围允许，重要知识就应在后续通过提取练习和分布式练习再次出现。不要凭一次即时成功就宣称学习者已掌握。

检索与生成活动的尝试前条件

如果任务是有意设计为引出无辅助检索或学习者生成（例如 QuickCheck 测试回忆，或要求学习者产出或生成目标答复的任务），那么在学习者首次尝试之前，学习者可见的提示材料和默认状态不应透露目标答复，也不应提供会消除预期检索或生成机会的决定性线索。

有关检索练习和生成效应的证据与适用边界，请参阅 references/research-foundations.md。

如果答复是有意作为示范教学、引导建模或支架式支持（示例、补全任务、逐渐撤除支持）提供的，那么这种学习者互动属于引导练习或验证，而非无辅助检索或生成。这与检索和生成原则相容，体现的是对支持形式的有意选择。

这并不意味着所有练习都必须隐藏答案、指导应始终尽量减少，或每次学习活动都必须最大限度地提高生成难度。任务设计应符合教学目标、学习者的知识水平以及所用策略的证据。

预测／预习提问活动应询问即将出现的具体关系或结果。证据支持对预先提问内容的益处；不要将这些益处泛化到无关且未预先提问的内容。关于新手在解释前预测代码输出的研究，支持在适当的初始编程教学中采用这一做法，而非将其作为任何场景下都必须遵循的模式。清晰呈现对象／代码，并要求给出具体结果。保留尝试前状态，避免泄露目标答案。尝试后，应针对实际结果或关系提供具体且聚焦任务的反馈，并给出因果解释或扩展反馈，而不只是判断对错。对于探索性预测，相比带有惩罚意味的错误标签，采用支持性的比较措辞可能更合适；具体措辞、颜色和图标选择属于本地决策，并非研究推导出的要求。

在适合使用自我解释时，应为提示提供支架，以明确要解释的关系、错误或概念；笼统的“解释一下为什么”提示并不一定更好。自我解释文本非空并不能证明其正确性，也绝不要将未经评分的自由文本伪装成语义正确。如果完整解释会泄露原计划由学习者进行自我解释或生成的目标，应将反馈分阶段呈现：先验证并给出具体观察结果，再由学习者进行生成／自我解释，最后提供规范的因果解释或扩展解释。如果反思内容不进行语义评分，就不要设置虚假的强制关卡；在适当情况下，允许回答“我不知道”，或让学习者通过明确的途径查看解释或答案。在有帮助时，将学习者生成的完整陈述与规范解释并列展示。仅在概念转换处选择性地使用自我解释，而不是每次操作后都使用。

如果“已记录”“已添加”或“结果显示如下”等状态说明不能带来学习、行动、恢复、方向指引或无障碍方面的价值，就应将其移除。如果第二次出现完全相同的可见结果句子没有独特作用，就不要重复。不要机械地将视觉结果与简洁的文字对应说明或无障碍替代内容视为无谓重复。Shute（2008）以及 Van der Kleij、Feskens 和 Eggen（2015）的反馈研究结论，在其明确的适用边界内属于 R 级指导；分阶段序列是 S Course Docs 的综合建议；具体措辞、语气、颜色和图标样式属于 L 级本地决策。

恢复与错误支持

精简的错误支持涵盖预防、检测、诊断和恢复。 <Recovery> 样式的组件本身主要负责响应。

• 如果常见错误可以低成本避免，请在操作前给出预防性警告。
• 在可能发生故障的环节之后加入 Recovery。
• 将 Recovery 组织为症状 → 可能原因 → 具体修复方法。
• 不要在章节末尾使用笼统的“重试”建议。

信号提示与一致性

仅在有助于学习者查找、映射、排序或理解与目标相关的信息时使用信号提示。

好的信号提示包括简洁的目标、视觉标注、重要的 UI 标签、需要输入的确切值或关键手势。装饰性强调不属于信号提示。

让重要的任务相关信息在视觉上醒目，同时限制相互竞争的强调元素，以保持信号的选择性。使用邻近、共同区域、对齐或连接等分组线索，前提是它们能传达真实的语义结构。当含义或操作相同时，保持任务与操作的映射关系及提示一致。这些方向有研究支持，但这并不意味着可以凭空指定确切的颜色、边框宽度、圆角、间距或组件系列，并称其为研究结论。

去除与学习目标无关的装饰或情绪刺激。只要情感化设计与目标一致，且不会造成相互竞争的认知负担，就可以有意采用它来支持学习动机或注意力。侧边栏、视觉内容、音频或动态效果，只有在实际承担任务、警告、参考、无障碍、解释或反馈作用时才合适。

不要把任意的强调次数当作科学规律。如果平台的 lint 检查指出粗体使用异常密集，应将其视为检查视觉信号是否相互竞争的提示。

当学习者需要整合代码、UI、图表或渲染结果时，应明确说明它们之间的语义关系，并在适当时使用邻近、共同区域或有选择性的映射提示。不要假设新手会自行推断，附近的预览是由某种 HTML/CSS 状态生成的。辅助标记不得造成新的解码任务：应直接解释标签，而不要依赖 A + B → C 之类未加说明的符号。具体采用左右布局还是上下布局，仍由具体情况决定；研究并未证明某种布局最优。先用学习者熟悉的语言为渲染面板命名（例如“浏览器结果”），再依赖这一概念；并优先使用稳定的对象名称，而不是布局位置。

面向学习者的正文

清晰度 > 简洁性。 不要为了缩短内容而省略因果关系、界面与状态之间的对应关系、某项操作的重要性、状态转换，或学习者需要了解的术语含义。术语可以先出现在标题或题目中，再作定义；但在要求学习者理解之前，必须先解释清楚。标题应尽量明确提示任务、主题或所需能力。

使用自然、直接、主动的表达。日语中省略主语的句子没有问题；不必明确写出「あなた」。

如果编写理由和受众分类对完成任务没有帮助，就不要写进面向学习者的正文。将「受講者は〜」「学習者は〜」「初学者向け」改写为面向任务的表述。若「ユーザー」指的是实际产品或领域中的终端用户，则不必禁用这个词。

使用 S — 面向学习者的可见正文价值测试：如果一句面向学习者的文字不能实质性地帮助理解、做出决策、采取下一步行动、防止或解决错误、解读状态、查阅参考资料或提升无障碍体验，就考虑删去或改写。只重复显而易见的操作或结果的界面描述通常没有必要。保留可客观评分的验证内容（用于消除学习者的不确定感）、有用的表现反馈、因果解释、预防误解的内容、任务指引、有用的状态／无障碍消息，以及能提升清晰度的补充说明。这并不意味着“越短越好”：清晰表达和有用的补充说明会有所帮助，而单纯降低复杂度并不能可靠地提升 STEM 文本学习效果。面向用户的可见正文与辅助技术状态消息用途不同。无障碍等效内容并非无谓重复。请参阅references/research-foundations.md中的限定范围综合分析。

冷读：检测意外难点

按内容渲染后的顺序阅读材料，检查是否存在未解释的前置知识、含糊的指令、缺失的状态信息、不必要的回溯、未定义的假设、术语缺漏，以及视觉内容与文字不一致等问题。在材料条件允许的地方，应确保学习者重新进入内容时能够理解。

保留预期的提取练习、问题解决、决策、富有成效的挣扎，以及在条件变化后的迁移应用。冷读审查应消除意外困惑，而不是替学习者解决有意义的挑战。

无障碍基础要点

将这些规则应用于所有提供信息的非文本内容，而不仅是特定组件中的截图。

• 提供具有相同用途或传达核心信息的文本替代内容。
• 对于带有复杂注释的视觉内容，使用简洁的短文本替代内容，并提供学习者可见或以其他方式关联的详细描述。
• 不要仅依靠颜色传达含义。
• 普通文本／文本图像的对比度需达到 4.5:1；大号文本可使用 3:1。具有意义的非文本 UI／图形指示器需满足适用的 3:1 非文本对比度要求。
• 在实际可行且呈现效果相当时，优先使用真实文本，而非文本图像。
• 交互示例必须支持键盘操作。
• 当状态变化的操作对理解很重要时，应明确指出发生变化的源、目标或结果，而不要要求学习者凭记忆进行比较。动画本身不能作为提示；应保留变化后的值／行标记、结果文本或等效内容，直到学习者能够查看。动态效果可以帮助体现连续性，但只能作为补充。尊重减少动态效果的偏好，并确保过渡期间的文本／UI 对比度。若直接的视觉提示已经清晰，且文字说明不会带来学习价值，则不要叙述每一处变化。
• 在按顺序推进的动态教程中，新显示的说明通常应出现在触发它的操作之后，或与该操作同时出现，并遵循有意义的阅读／焦点顺序；不要静默修改更早出现的说明，迫使学习者回头查找。若顺序会影响含义，应保持语义、视觉、DOM／阅读和键盘焦点顺序一致。通常自上而下、可预测的阅读流程是此类教程的本地默认方式，并非适用于所有布局或语言的普遍规则。重大步骤变化应能在学习者当前位置附近得到理解；远处的进度指示器可以作为补充，但单靠它不足以作为主要提示。
• 对于只有一个主要提交／确认操作的交互式单行回答，优先采用原生表单语义，以便 Enter 键和可见的提交控件在适用情况下调用相同的验证和状态转换。不要将此规则用于多行输入，或键盘标准操作方式不同的控件。避免使用自定义 Enter 处理程序在 IME 组合输入期间提交内容，除非明确处理了组合输入。

WCAG 2.2 AA 是此技能的默认无障碍目标。当材料属于美国联邦 ICT 范围时，还需考虑美国 Section 508 E205；它并非适用于每个教程的普遍法律要求。

在创作或审核说明性图片、示意图、图表、带注释的截图或交互示例时，请加载 references/accessibility.md。

视频也属于此技能的范围。当动态效果、时序或连续变化对理解或执行任务很重要时，请使用视频；并确保可通过无障碍文本获取准确值和命令。加载 references/video.md，了解学习者控制、提示、分段、同步和基于时间的媒体无障碍要求。

Course Docs 环境

当目标站点使用 @metyatech/course-docs-platform 时，请加载 references/course-docs-platform.md。

该参考文件包含本地 MDX 规范，例如：

• 每个层级可选的 <Section> 导向目标；
• QuickCheck/Exercise 的 problem → Hint* → Answer 结构；
• Verify 源码标注；
• 组件放置约定；
• lint 规则 ID 和严重级别。

不要将这些平台规范泛化为普遍适用的教程科学结论，也不要强行套用于无关的 Markdown／教程系统。

最终审查

交付或批准教程前：

• 核实预期的教学目标（初次表现、学习成效，包括保持、迁移，或这些目标的组合）是否足够明确，能够指导设计决策；
• 核实页面是否按照学习者目标组织；
• 按照渲染后的顺序，逐一通读每个标题、术语、数值、比喻和代码注释；
• 确认表征方式及其无障碍替代方案；
• 确认「概念」的安排有助于有意义的使用，或有意用于预先训练、总结、检索或参考；
• 确认提供的帮助与学习者的先验知识和表现相匹配；
• 确认「证据」在学习进程中的适当节点检验「单元」成果；
• 确认参与度支持有意义的挑战，而非将乐趣等同于轻松；
• 确认失败支持能够应对合理预期的失败情况；
• 移除无关或重复的处理内容；
• 使用 REVIEW-CHECKLIST.md 进行完整审查。

本技能采用了以证据为依据的默认做法和本地质量惯例；但这不保证产出在教学上正确。观察真实学习者，并在实际使用证据与假设的启发式做法相冲突时进行修订。