tutorial-authoring（教程创作）

Tutorial authoring

Use this skill when writing, revising, or auditing any document where a reader follows steps to build or achieve something.

Target learner (expertise reversal boundary)

This skill is optimised for beginner-to-intermediate learners encountering the subject for the first or second time. Most multimedia learning principles (Signaling, Pre-training, Personalization, heavy imagery) are strongest in that range and weaken — or reverse — for experts (Kalyuga's *expertise reversal effect*). If the artefact is an expert-facing quick reference, the author MUST scale back Signaling, Concept density, and hand-holding narrative, and lean on Reference tables. When in doubt, state the target learner explicitly in the document's opening.

Scientific foundations

All authoring rules below derive from the principles in this table. Principles are stated so their scopes do NOT overlap; when two seem to conflict, the "Scope & limits" column resolves the boundary. The agent MUST apply them actively when writing new tutorials and when reviewing existing ones.

Underlying load model (Sweller's CLT)

Every principle in the table below is a tactic for managing one of the three load types in Cognitive Load Theory (Sweller, 1988). When two principles compete, resolve by asking *which load type currently dominates*.

Expertise reversal (Kalyuga, 2007) predicts that tactics which reduce extraneous load for novices can *increase* extraneous load for experts (because redundant signals compete with established schemas). This is why the skill scopes itself to beginner-to-intermediate learners.

Citation note: The Mayer principles above cite the 2nd edition (Mayer, 2009) which defined 12 principles. The 3rd edition (Mayer, 2021) expanded to 15, adding Split-attention, Transient information, and Immersion. This skill incorporates Split-attention (relevant to static tutorials) and notes Immersion as out-of-scope. Transient information applies to video/animation tutorials and is not covered here; consult Jiang & Sweller (2021) when authoring such content.

Principles not applicable to static text-and-image tutorials

The following are canonical CTML principles, but they require audio or speaker presence and therefore are not applicable to static text-and-image tutorials. If the artefact is a narrated video or an avatar-driven walkthrough, these principles MUST be applied from the primary sources — this skill does not cover their application.

Authors writing narrated video or VR content MUST NOT assume this skill covers these principles; apply them separately from Mayer & Fiorella (2021), *Cambridge Handbook of Multimedia Learning* (3rd ed.).

Information hierarchy

Every tutorial MUST be composed of exactly these layers:

Tutorial (page)
 ├── Prerequisites — what the learner needs before starting (optional)
 └── Section (depth 0) — milestone ("when done, you can X"); `goal` required
      ├── goal — 1 future-tense sentence declaring what the learner will achieve
      ├── Concept × N — term/background, always collapsible, before first use
      ├── Reference × N — lookup tables, always collapsible, near relevant sub-section
      ├── Section × N (depth 1+, nested) — a group of actions toward one sub-goal
      │    ├── goal — optional at depth > 0 (use to express sub-goal in task language)
      │    ├── Action × N — the atomic unit (image + instruction + result)
      │    ├── Recovery — error recovery, inline, after the action that can fail
      │    └── Verify — "→ expected result" (1 text line; optional result screenshot)
      ├── Checkpoint — end-of-section checklist (exactly one per top-level Section)
      └── NextSteps — what to do after the tutorial (final top-level Section only, optional)

A single <Section> component is used recursively — it replaces what earlier versions of this skill called <Step> (top-level milestone) and <Procedure> (sub-goal grouping). Nesting depth is computed at compile time and mapped to h2 (depth 0) → h3 → h4 → … capped at h6.

Seven information types and display rules

Image / text / video hierarchy

Atomic unit: Action

The smallest learning unit is:

[Image: WHERE to interact] → [Text: WHAT to do] → [Text: WHAT happens (optional)]

Rules:

• The author MUST use one image per action. The author MUST NOT batch images. *(mechanised: tutorial/action-single-image)*
• The image MUST be placed above or before the text (spatial contiguity).
• The author MUST NOT describe in text what the image already shows (redundancy elimination).
• The image and the text MUST cover non-overlapping channels: the image carries WHERE (position, visual anchor, step ordering via numbered callouts); the text carries the imperative WHAT plus any values the image cannot convey.
• The author MUST keep in the text: values the learner types by hand (e.g. UE90min, CLEAR!), user-specific paths the screenshot cannot generalise, and UI element names that are not labelled in the shot.
• The author MUST remove from the text: positional prefixes when the image already shows position *(mechanised: tutorial/action-positional-prefix)*; label/value pairs already paired in the image's numbered callouts; micro- interaction details already conveyed by the image's arrows or step markers.
• Reducing Action text to a bare verb such as "クリックします" MUST NOT be used as a redundancy fix. The imperative WHAT plus the values the image cannot convey is the minimum; strip only what the image already carries.
• If the action produces a visible result, the author MUST state it inline. The author MUST NOT create a separate Verify for this — Verify is reserved for Section-level confirmation only.

Signaling (visual cueing)

学習者の注意を本質的な情報に誘導するために、情報階層を視覚的な 合図で表現する。合図は学習目的に沿った要素にのみ付ける。

Signaling surfaces in this skill:

Rules:

• 合図は必ず学習目的に沿うこと。装飾目的の太字、感情表現の 強調、文末の飾り記号は Signaling ではなく一貫性原理違反。
• 画像の番号吹き出しとテキストの ① 番号は併記する（Sequence channel の二重化は Redundancy に該当しない補完関係）。
• 太字の濫用（1 文に 3 箇所以上など）は合図の効力を破壊するため 禁止。強調は本当に注視すべき要素のみに絞る。

Personalization (reader-addressing voice)

学習者に直接語りかける二人称・能動・会話的な文体で書く。

Rules:

• Use second-person direct address to the reader. Do not describe the reader in third person ("受講者が〜する", "初学者が〜", "学習者は〜").
• Use active, conversational Japanese: 「〜しましょう」 「〜してください」「ここで〜を確認します」.
• Do not open a page by describing what the document *is* or *who it is for* ("この教材は〜のための資料です" は NG). Open with the first learner-facing step or an inviting goal statement.
• Personalization is about friendliness, not familiarity. Emoji spam, 余談, 感情過剰な装飾はむしろ Coherence 原理違反 になるため避ける。親しみやすさの上限は「先輩が隣で教えて くれる」程度が目安。
• Goal strings already use future-declarative form; they also implicitly address the reader — do not revert them to third-person ("受講者が〜する状態になります" は Goal と Personalization の両方に違反する).

Accessibility (authoring obligations)

画像主体のチュートリアルでは、アクセシビリティはプラットフォーム 実装の責務とオーサリングの責務の両方にまたがる。以下はオーサ リング段階で著者が守るべき最低限のルール（WCAG 2.2 Level AA 準拠、 Section 508 E205 の教育・訓練資料要件に基づく）。

Rules:

• Every <Action> image MUST have an alt prop that describes what the image shows in the context of the step. The alt text MUST convey the WHERE information (which panel, which button, which area) so that a screen-reader user can follow the procedure without seeing the image. If the image is purely decorative (rare in tutorials), use alt="".
• Numbered callouts, arrows, and highlights in images MUST NOT rely on colour alone to convey meaning. Pair colour with shape (numbered circles, arrows with labels) so that readers with colour vision deficiencies can follow the sequence (WCAG SC 1.4.1).
• When an image conveys information not present anywhere in the surrounding text (e.g. a UI layout, a spatial relationship between panels), the author MUST provide a text equivalent nearby — either in the Action text, a Concept, or a Reference — so that the meaning is recoverable without the image.
• Text annotations overlaid on screenshots MUST meet a minimum contrast ratio of 3:1 against the background they sit on (WCAG SC 1.4.11 for non-text UI components).
• The tutorial's heading hierarchy is produced by <Section> nesting depth (depth 0 → h2, depth 1 → h3, … capped at h6). The remark-section-headings plugin injects these semantic headings automatically so that screen-reader navigation by heading works correctly.
• Interactive examples or embedded widgets (if any) MUST be operable by keyboard alone in a logical tab order.

Generative activity (prediction / retrieval)

学習者が受動的に読むだけにならないよう、生成活動（予測・ 説明・自己確認）を組み込む。活動は必ず学習目的に関連させる。

Surfaces:

Rules:

• Verify の文面は「観察可能な状態」で書く（例: 「キューブが 消えれば成功」）。内部処理・実行履歴の記述（例: 「Destroy Actor が実行されました」）は生成活動を奪う。
• Checkpoint の項目は学習者自身が視覚・操作で確かめられる内容に 限定。内部状態や jargon は不可。
• Exercise は学習目的に関連していること。作業量稼ぎの演習、 本筋と関係ない応用は一貫性原理違反。
• 予測を促すプロンプト（「実行前に、何が起こるか予想してみて ください」）は有効だが、過剰使用は認知負荷を上げる。Step ごとに 1 回が目安。

Progressive independence (scaffolding / fading)

ワークトエグザンプル効果と生成活動原理を組み合わせて、チュートリアル 全体を通して段階的に足場を外す構成にする（Van de Pol et al., 2010; backward fading: Renkl et al., 2002）。

静的チュートリアルにおける段階的撤退の実装:

Rules:

• Tutorial の最初の Step は Phase 1（完全例）で始める。 いきなり Phase 3 の独立課題を出すのはミニマリズム P1 と ワークトエグザンプル効果に反する。
• Phase 間の移行は同種の手順の繰り返しで自然に起こる。 同じ操作パターンが 2 回目に出るときに Phase 2 へ、 3 回目以降に Phase 3 へ移行するのが目安。
• Phase 2 の Exercise では、変更点（差分）を明示し、学習者が ゼロから構成する必要がない形にする。
• 足場の撤退量は対象読者の熟達度に比例させる。beginner 向け では Phase 1 を長めに、intermediate 向けでは Phase 2 から 開始してもよい。

Writing rules

Goal text

• The goal string is rendered verbatim as a banner directly below the section heading; no prefix such as "ゴール:" is added. It MUST read as a complete sentence on its own. Bare noun-phrase endings such as 「〜した状態」 are forbidden because they render as incomplete prose.
• The author MUST write goals in future-declarative form describing what the learner will achieve by the time the section is complete:

- Action completion → 「〜します」（例: 「キューブを 1 つ置きます」） - Acquired capability → 「〜できるようになります」（例: 「キャラクターを操作できるようになります」） - Acquired behavior / state → 「〜ようになります」 / 「〜の状態になります」（例: 「触れたら消えるようになります」）

• The author MUST NOT write goals in past or completed form (「〜した」「〜された」「〜した状態」「〜している」「〜できます」) because those frame the section as a retrospective of what already happened instead of a preview of what the learner is about to build. *(mechanised: tutorial/section-goal-required, tutorial/section-goal-tense)*

Action text

• The author MUST use the imperative mood: 「〜をクリックします」 「〜と入力します」.
• The author MUST name a UI element in bold only when the image does not clearly label it with a visible caption or a numbered callout, or cannot disambiguate it from similar elements. Repeating an image-labelled element in text violates the Redundancy principle; Identity is image-primary when labelled in the shot (see the WHERE/WHAT channel rules in Atomic unit: Action).
• Panel and location names appear inline on first use only when the shot does not already make the panel unambiguous. A full-screen screenshot that shows the panel in context does not require redundant naming in text.
• Regardless of the above, values the learner must type (e.g. UE90min), user-specific paths, and gestures/motions (drag direction, hover vs click) MUST remain in text because a still image cannot convey them.

Concept text

Concept serves the Pre-training principle: it teaches the *name* and the *key features* of a term the learner is about to encounter, so that main-task cognitive load is reduced.

• A Concept MUST be at most 5 sentences or 1 short table.
• A Concept MUST answer "what is it?" (name + key features) and "why does the learner need to know right now?".
• A Concept MUST be placed immediately before the first Section that uses the term. Placing Concepts far upfront violates Minimalism; omitting them until after first use violates Pre-training.
• Concepts for terms that appear much later MUST NOT be written now. Pre-training applies to the *next* sub-task, not to the entire page.
• If a Concept needs more than 5 sentences, the author MUST split it into multiple Concepts and place each before its own first-use Section.

Verify text

• In component-based tutorials the Verify component renders its own leading →; the author MUST NOT include → in the source or the rendered output will have a doubled arrow. *(mechanised: tutorial/verify-no-duplicate-arrow)*
• In plain-Markdown tutorials (no component), the Verify line MUST start with →.
• A Verify line MUST describe observable state, not internal mechanics:

- ✅ 「キューブが消えれば成功です」 - ❌ 「Destroy Actor が実行されました」

Prerequisites text

• Prerequisites MUST appear at the page top, before the first top-level Section.
• Each prerequisite MUST be actionable or verifiable: state the required software version, completed prior tutorial, or assumed knowledge concretely.

- ✅ 「Unreal Engine 5.4 以上がインストール済みであること」 - ✅ 「Step 1〜3（前回のチュートリアル）を完了していること」 - ❌ 「基本的な知識があること」(what knowledge?)

• If no prerequisites exist, omit the section entirely (do not write "特になし").

Recovery text

Recovery serves ミニマリズム P3 (error recognition and recovery support). It covers the full error lifecycle: prevention, detection, and correction.

• A Recovery block MUST be placed after the Action that can plausibly fail.
• A Recovery block MUST follow the structure: symptom → cause → fix (in that order). The symptom comes first because the learner sees the symptom, not the cause.

- ✅ 「ブループリントが動かない場合 → コンパイルエラーが 出ていないか確認してください → ノード名のタイプミスが 原因です。正しい名前は〜」 - ❌ 「うまくいかない場合はやり直してください」

• For actions with a high failure probability, the author SHOULD place a preventive note (1 sentence) immediately before the Action, warning about the common mistake. This note is distinct from Recovery (which is reactive).
• Recovery MUST NOT be placed at the end of a Section as a catch-all. Each Recovery block addresses a specific failure point.

Next steps text

• Next steps MUST appear only at the end of the final top-level Section or after the last Checkpoint.
• Each item MUST link to a concrete next action: another tutorial, a documentation page, or an exercise.
• The author MUST NOT use vague pointers ("詳しくは公式 ドキュメントを参照してください" without a link).

Checkpoint

• A Checkpoint MUST be a bullet list of observable behaviors.
• A Checkpoint MUST NOT include internal state or jargon.
• Exactly one Checkpoint per top-level Section, placed as the last element of that Section. *(mechanised: tutorial/checkpoint-placement)*

Anti-patterns (do NOT do)

Judgement-based anti-patterns; a tool cannot reliably detect these, so the author is responsible for catching them.

Mechanised checks (enforced at MDX build/dev time)

The following conventions are enforced by the remarkTutorialLint plugin in @metyatech/course-docs-platform. Violations surface in npm run dev and npm run build output; author reliance on memory is not required.

Severity policy (evidence-tiered)

Severity is tied to how strongly the rule is anchored in the underlying research, so the tool does not over-reach.

TUTORIAL_LINT_COLLECT=1 aggregates every finding in a file into a single failure message, so a PR author can fix all violations in one pass instead of one at a time. If the aggregated collection contains only notes, the summary is printed via console.info and the build still passes.

Rule → severity mapping

The *note* tier exists because these rules are correct in principle but their specific numeric boundary or lexical trigger has no direct empirical backing — they are the authoring equivalent of professional code review hints, not hard gates.

Page authoring mode (frontmatter)

Tutorial pages MUST declare their authoring mode in frontmatter so the lint plugin can apply tutorial-specific rules only to tutorial pages:

---
title: ページタイトル
authoringMode: 'tutorial'
---

Mode values:

Mixing modes on one page is not supported. A page that mixes tutorial structure with free-form narrative MUST either be split, or be authored as non-tutorial without <Section>.

Component system (course-docs-platform)

When writing for @metyatech/course-docs-platform-based sites, the author MUST use the provided MDX components. They are globally available (no import needed):

---
title: コリジョンを設定する
authoringMode: 'tutorial'
---

<Section title="Step N：コリジョンを設定する" goal="アイテムに触れると消えてスコアが増えるようになります">

  <Concept title="コリジョンとは">
    当たり判定のこと。ブロック＝壁、オーバーラップ＝すり抜け＋検知。
  </Concept>

  <Section title="N-1. 触れたことを検知できるようにする" goal="アイテムをすり抜けて通れるようになります">
    <Action img="./img/overlap-events-on.png">
      **Generate Overlap Events** をオンにする
    </Action>
    <Action img="./img/overlap-all-dynamic.png">
      **コリジョンプリセット**を **OverlapAllDynamic** に変更する
    </Action>
    <Verify>アイテムをすり抜けて通れる</Verify>
  </Section>

  <Checkpoint>
    - アイテムに触れるとスコアが増える
    - アイテムに触れると消える
  </Checkpoint>

</Section>

A single <Section> is used recursively at both the milestone level (depth 0) and the sub-goal grouping level (depth > 0). Nesting depth maps to heading level: h2 → h3 → … capped at h6.

Components

Non-component tutorials

When components are not available (plain Markdown, Docusaurus, etc.), the author MUST apply the same information hierarchy using native syntax:

The hierarchy and writing rules MUST remain identical regardless of tooling.

Limits of principled authoring

This skill encodes the best available tactics, but it does not guarantee pedagogically correct output. Authors and reviewers MUST treat the following as known limitations.

Semantic checks that tooling cannot enforce

The remarkTutorialLint plugin catches structural violations only. The following judgements are author-only; treat them as explicit review gates, not as automated safety nets.

Generalisation limits of the underlying research

• Mayer's effect sizes were measured primarily on educational videos and science lessons with short durations. Applying them to long-form software tutorials requires extrapolation; the *direction* of each effect is robust, but magnitude is not guaranteed.
• Most studies use novice learners in controlled settings. Real-world learners mix expertise levels, read non-linearly, and bring prior frustration. The skill's rules are the *baseline*, not a replacement for observing real learners.
• Language and cultural effects on Personalization / Voice have been studied mainly in English. Japanese-specific tactics (「〜しましょう」 vs 「〜します」 の丁寧度階調, etc.) are transferred by analogy, not by direct evidence.

When principles appear to conflict

1. Identify which load type (Intrinsic / Extraneous / Germane) is currently dominant for the target learner at this step.
2. Apply the principle that directly addresses that load type.
3. If still ambiguous, ask *which tactic would a novice benefit more from right now?* — the skill is novice-biased.
4. If the conflict involves an out-of-scope principle (Voice, Image, Embodiment, Immersion), treat it as not resolved by this skill and consult the primary sources.

Self-review

Use REVIEW-CHECKLIST.md (same repository) as a reviewer-facing checklist. It mirrors the principle table and is the single place to audit a draft tutorial against every principle in sequence.