Reusable Specification Template — Interactive Technical & Professional Tutorial

Template v1.3 · 19 October 2026 (editorial direction accepted after sample review)
Purpose: describe a learning product before implementing chapters and website features. Copy this file into a new tutorial project and replace [TBD] fields. Mark each requirement MUST, SHOULD, MAY, or NOT APPLICABLE. The template is intentionally platform-neutral: Astro/GitHub is one possible implementation.

0. Specification identity and decisions

Decision record. Track significant choices using Decision · rationale · alternative · status · date. Do not treat tentative design ideas as verified capabilities.

1. Product intent and reader value

Problem: [What learning problem does the tutorial solve?]
Promise: After using it, readers can [observable capability].
Why now: [Why does this matter to them?]
Differentiation: [What can a reader do here that another article/book cannot provide?]
Owner acceptance: [How will the tutorial owner decide the experience communicates the intended insight?] Optional future reader evidence: [How broader audience testing could be added later without blocking current delivery.]

Define no more than 3–5 overall learning outcomes. Prefer verbs such as identify, distinguish, explain, inspect, evaluate, apply, or build, not merely understand.

Reader profiles and entry routes

State prerequisites explicitly. MUST: Core learning works in a browser without a local installation or external account. MAY: Offer a clearly labeled advanced local track.

2. Learning model and curriculum architecture

Narrative arc: [Why it matters] → [How it works] → [What it enables] → [How to apply it] (adapt to the subject).

Groups should represent distinct stages of capability, not arbitrary chapter counts.

Progression rule (MUST): Every chapter contributes a demonstrably new insight or capability. Delete, merge, or move redundant material into a reference. Record conceptual prerequisites, transitions between examples, and the one question each chapter answers.

Chapter contract — repeat for every chapter

number: 0
slug: short-stable-slug
title: "[Conversational, reader-oriented title]"
group: G1
reader_question: "[Question answered by this chapter]"
learning_outcome: "[Observable capability]"
prerequisites: []
key_concepts: ["[maximum 3–5]"]
not_in_scope: ["[What belongs elsewhere]"]
scenario: "[Common example or new example with clear handoff]"
narrative:
  reader_motivation: "[What real reader problem opens the chapter?]"
  opening_example: "[Concrete situation before extended terminology]"
  new_insight: "[What is genuinely new here, not repeated from earlier chapters?]"
  transition_in: "[What from the previous chapter is assumed?]"
  transition_out: "[What question remains for the next chapter?]"
  avoid_repeating: ["[Ideas already taught elsewhere]"]
evidence_or_source: ["[Which maintained records or verified facts]"]
primary_visual:
  purpose: "[What becomes clearer?]"
  type: "[diagram, before-after, annotated UI, graph, illustration, none]"
learning_interaction:
  mode: "read-only | quiz | on-page-lab | optional-local | combined"
  action: "[What the reader actually does, if anything]"
  feedback: "[What new understanding the response reveals]"
  loop: "observe-only | predict-act-observe-explain | guided-discovery | exploration"
  first_action: "[One safe, intelligible action or choice; optional if not appropriate]"
  hints: ["[Optional first nudge]", "[Optional worked explanation]"]
  state_visibility: "[What is current, modified, valid, generated, saved, or published?]"
  reflection: "[One-sentence explanation of why the result matters]"
  reset_or_recovery: "[How readers safely retry or undo without losing track]"
scenario_check:
  enabled: false # optional; decide based on genuine misconception
  misconception: "[What plausible but wrong interpretation is examined?]"
  answer_feedback: "[Why is the chosen decision justified?]"
  no_score: true
supporting_links:
  - target: "[Stable link to a reference or external source]"
    reader_benefit: "[Concrete answer or useful capability at destination]"
    placement: "[At point of need; optional deeper reading]"
completion_signal: "[How reader knows they got it]"
next_chapter_bridge: "[Why the next chapter follows]"
acceptance_checks: ["[2–4 observable tests]"]

Editorial structure (SHOULD): Start with a concrete question or surprise; show the core example; introduce no more than a handful of new concepts; demonstrate the result; offer one optional path deeper; end with a meaningful takeaway and a transition. A chapter does not need every section in the same order.

Length guidance: Aim for roughly 500–850 words of core prose. A complex, valuable chapter may be longer; shorten repetition, not useful explanation. Keep implementation tutorials and lengthy source listings in references.

Editorial voice and reading-flow contract (MUST for reader-facing chapters)

Intended voice: direct, warm, clear, intellectually respectful, and practical. Write for a curious professional who may not know Git, Astro or YAML but is capable of complex reasoning. Explain ideas, not just labels. Avoid marketing language, lectures, artificial enthusiasm, and school-style homework framing.

Narrative sequence (flexible, not mandatory headings): reader problem or question → concrete example → the smallest necessary explanation → diagram or interaction where it clarifies → insight/consequence → natural transition. Begin with the reader’s reason to care, not a list of chapter objectives or a recap of the previous chapter.

Paragraph/section review rules:

• One central idea per paragraph; favor active verbs and specific actors over abstract nouns or excessive passive voice.
• Introduce unfamiliar terms when they become necessary. Define a term once; afterward use it consistently and link to the glossary rather than redefine it in every chapter.
• Explain cause and consequence. Prefer “If the source changes, the guide can be rebuilt” to a string of nouns such as “source-based transformation enables repeatable publication”.
• Use you for reader actions, we sparingly for a shared walkthrough, and the project’s actual actors when describing approvals and responsibilities. Avoid unexplained shifts in viewpoint.
• Prefer a short paragraph to a numbered list when the content is a coherent thought. Use tables only for meaningful comparisons or structured reference—not to interrupt a story with a mini-glossary.
• Keep constraints and qualifications close to the claim or result they qualify, especially approval, status, permissions, live vs snapshot and inferred impacts. Do not delete important distinctions merely to shorten text. Eliminate duplicate disclaimers, not their meaning.
• Avoid excessive “in this chapter”, “as we have seen”, “what to remember”, “this demonstrates”, repeated “maintained information”, and generic handoffs. Use a natural opening and closing instead of formulaic headings where possible.
• Prefer short headings that reveal a reader question or insight over mechanical topic labels. Make scanning easy without turning every paragraph into an isolated callout.
• Writing length is a guide, not an optimization metric. Reduce repeated explanations and weak framing before cutting useful examples. Never use an automated word-count target as a proxy for quality.

Across-chapter continuity (MUST): Maintain a curriculum map with the example in use, previously established knowledge, the single new insight, and the next reader question for each chapter. Whenever the example changes (onboarding → agent working environment → contracts → this site’s real architecture), include one or two sentences explaining why the new example is useful. Maintain consistency of names, status meanings and source identity.

Interaction microcopy (MUST when present): Introduce the situation in everyday language, use one clear action verb on the control (“Check answer”, “Validate metadata”, “Explore relationships”), report what happened, and explain why it matters. Avoid “Correct!” as the entire feedback and never imply that green means approved. Hints, reset and data-persistence explanations must be easy to find without crowding the narrative.

Supporting-link wording (SHOULD): Say what the reader will learn or be able to do, not merely “Read more”. Links to technical implementation or local exercises declare prerequisites and remain optional. Link labels must remain descriptive out of context.

Accessibility of language: Acronyms are expanded at first meaningful use, examples are understandable without color or figure position, link purposes are explicit, and captions convey the conclusion rather than restating shapes. Prefer everyday language without becoming patronizing.

Editorial acceptance review (owner-led)

Review every proposed chapter change with five checks:

1. Opening: Is the reader’s question clear within the first ~100 words without making false claims?
2. Flow: Can we follow the explanation from example to insight without a conceptual leap or a long detour?
3. Novelty: What does this chapter add that earlier chapters did not?
4. Economy: Can a sentence, list, table or qualification be cut or moved to a supporting page without losing meaning?
5. Finish: Does the reader leave with one useful understanding and a natural reason to continue or go deeper?

Submit a before/after excerpt, a short explanation of editorial intent, and a map of changed references for owner evaluation. Build/lint automation catches broken files, not awkward prose. Read-aloud and skim reviews are editorial techniques, not quantified learning evidence. Do not require participant testing or invented readability scores.

3. Examples, stories, and source fidelity

Create an example register. A single evolving example can teach progression; a new example can broaden applicability, but the transition should be explicit.

MUST: Distinguish source facts, illustrative assumptions, inferred relationships, and generated outputs. Never represent a fictional dashboard, unsent request, unexecuted test, or draft as a live or approved result.

SHOULD: Reuse one example across chapters when it reinforces progression. Avoid forcing a domain-specific example on readers when a business, logistics, public-sector, or engineering example would better explain the concept.

4. Engagement model: visual, interactive, or simply clear?

Choose the least demanding interaction that makes the learning better. An exercise is not a mandatory ingredient.

MUST: No inert controls. Interactive widgets state whether data are fictional, build-time snapshots, current/live, or locally edited, and whether actions persist. Include non-JavaScript or accessible alternatives. Never make an off-site tool, paid account, installation, or homework a hidden prerequisite for a core chapter.

Activity micro-lesson contract (SHOULD for labs, not every chapter)

The reusable pattern is invite / predict → act → observe → explain → explore further. Choose the smallest useful subset, not a mandatory six-screen wizard:

1. Orient. Name the question and expected action in plain language, before showing all controls.
2. Predict or attempt (optional). Ask one low-stakes question before revealing the answer when the reader has enough context to make a meaningful prediction. Offer a Show an example / Give me a hint path immediately when they do not.
3. Act. Let the reader change one variable or make one selection; keep the relevant output visible alongside the source when space permits.
4. Observe. Give an unmistakable result, diagnostic, or visual change. Explicitly distinguish a preview, validated result, and published output; don’t automatically claim that a change was checked or saved.
5. Explain. Provide a one- or two-sentence causal explanation, including why a valid result can still be semantically wrong.
6. Explore further. Offer reset/retry, an optional second variation, and a benefit-led reference link. Avoid compulsory multi-step tasks or tracking-based completion incentives.

MUST for an implemented lab: A self-explanatory first action; outcome and error feedback near the control; optional help or a worked example; safe retry/reset; an understandable learning takeaway; accurate state labels; keyboard/focus/status-message support. The learner must not have to finish an activity to continue reading. SHOULD: Do not interrupt every input with a modal or repetitive ‘incorrect’ toast; support an iterative edit–check cycle. Instantly showing changed preview is appropriate; instantly validating an unsubmitted draft may be misleading.

Source of pattern: Brilliant’s guided, bite-size problems and immediate feedback; Khan Academy’s optional progressive hints and rationales; and Code.org’s distinction between seeing a run result and passing a validation check. These are design inspirations—not independent evidence that copying a branded interface will improve learning. See §10.

Data exploration and visual storytelling (SHOULD when a graph is central)

Follow orient → focus → manipulate → interpret → inspect source. Begin with one useful relationship or question, reveal additional controls on request, and keep data definitions/provenance available. Borrow the idea of guided depth from Google Arts & Culture and connected inputs/views from Observable. Borrow restrained narrative pacing from The Pudding; do not introduce scroll-driven animation unless it teaches something beyond a static view. Preserve a keyboard-usable list/table alternative.

Quiz criterion: Distinguish an in-context scenario check from an optional end-of-chapter quiz. A scenario check is a self-contained practical decision with 2–4 plausible answers, explicit Check answer, immediate rationale, optional hint/retry, and no score, streak or persisted completion. Put it next to the relevant concept. It is NOT mandatory in every chapter. The general quiz can remain where it probes a different outcome; omit or trim repetitive questions.

Optional exercise criterion: Only include a procedure if hands-on execution adds a skill that the browser cannot teach. Mark Optional: 5–15 minutes, prerequisites, expected result, restore/reset steps. Do not silently turn the tutorial into a homework course.

5. Supporting content and deliberate cross-linking

References, glossary entries, downloadable artifacts, demonstrations, presentation decks, and source files are complementary products, not chapters hidden in the navigation.

Discovery rule (SHOULD): Link at the moment the reader encounters the question. Use descriptive text that sells the benefit, e.g., “Want to test this with your own records? Open the 10-minute validation guide,” rather than “See reference.” Show expected effort and prerequisites when relevant. Keep a route back to the chapter. Optional depth must not be required to understand the core sequence.

Reference rule (MUST): One subject has one primary maintained explanation. Summarize its intent in the chapter; maintain commands, edge cases, and tool versions in the reference. Avoid duplicating detailed instructions in multiple pages.

6. Visual language, design system, and UX

Desired experience: [e.g., calm, modern, inviting, precise; not a dense technical manual].

Visual vocabulary — define a modest system: colors/tokens, typography, spacing, cards, illustration style, diagram style, icon rules, light/dark assumptions, and captions. Prefer purposeful graphics over decoration.

Progressive disclosure rule (SHOULD): Show the essential action and result first; put advanced schemas, full Git provenance, options, and implementation details in explicitly labeled expandable or secondary views. Important safety/status qualifications must not be hidden.

Feedback and completion rule (SHOULD): After a successful activity show a small, calm “What this demonstrated” statement. Never confuse lesson completion, schema validation, approval, and publication. Errors should explain how to recover; users can skip or retry without penalty.

Page requirements (MUST/SHOULD): Consistent hierarchy; restrained line length; readable code/tables on mobile; obvious chapter progress and navigation; visible links and focus states; accessible keyboard and screen-reader interactions; descriptive alt text and captions; no important color-only meaning; explicit loading/error/empty states. Target WCAG 2.2 AA and verify, rather than claiming compliance from code inspection alone. Design is allowed to feel warm and graphical without distracting from learning.

Per-chapter design choice (SHOULD): At least one meaningful visual moment, unless the best representation is text. No arbitrary image quota; no placeholder diagrams repeating prose. Prefer reuse of layout/visual primitives to manually styling each chapter.

UX verification plan: Owner reviews representative desktop and mobile renderings and tests narrow tables/code, keyboard-only operation, no-JavaScript behavior, contrast, image alternatives, discoverability of labs, and return navigation from references. Include realistic focus traversal across tab controls, accessible status announcements, and whether hint/retry/reset flows make sense. Test visuals at 200% zoom and with reduced-motion preferences. Use W3C WAI tutorials and ARIA Authoring Practices as implementation references; the A11y Project checklist and axe/Lighthouse are supporting checks, not proof of WCAG conformance.

Performance evidence (SHOULD for public sites): Sample the homepage and one heavy interactive page using PageSpeed Insights/Lighthouse and, where sufficient field traffic exists, Search Console or Chrome UX Report. Track Core Web Vitals LCP, INP, CLS (current ‘good’ guidance: ≤2.5 s, ≤200 ms, ≤0.1 at the 75th percentile); benchmark actual measured performance rather than assume that Astro/static hosting is fast. Lighthouse alone does not measure real-user INP. Do not introduce invasive learner surveillance or a performance dashboard without a decision it supports. No external learner sessions are required for owner-led design acceptance. If later claiming demonstrated learning effectiveness across audiences, gather separate reader evidence; do not infer that claim from owner approval.

7. Technology architecture — choose, do not presume

MUST: Distinguish content source, generated output, publication, approval, and browser state. Document how one source change flows to relevant outputs. Access to a file is not the same as agent authorization to edit/publish it. An integrated Microsoft 365/SharePoint workflow may implement comparable principles but does not automatically supply Git branches or PRs.

Agent-ready project knowledge (SHOULD when agents maintain the tutorial)

Separate agent working instructions from maintained project knowledge. Define or link to the actual source for each topic—do not create parallel copies simply to fill a template.

AGENTS.md should be short, navigable and specific about scope; it must not pretend that all agent frameworks recognize it equally, that linked material is loaded automatically, or that file access grants permission to edit, publish, or disclose it. A decision log explains rationale rather than substituting for requirements. Source status, accuracy, authorization and deployment are independent.

Owner approval: Show any proposed new knowledge files and ADRs to the owner as a diff against existing guidance. Add only content supported by real decisions; mark unresolved choices proposed rather than fabricating acceptance history.

8. Content quality, evidence, and safety

Editorial rules: Follow the chapter voice and reading-flow contract above. For the target project, link CONTRIBUTING.md, its glossary and an adopted editorial style guide; do not leave the instructions as generic placeholders. Preserve technical precision, source status and intended meaning.

MUST: Technical claims link to suitable current sources; examples are clearly fictional or verified; no invented current capabilities; defined terms are consistent; specific version/tool claims are checked before publication; rights and attribution of media are recorded; sensitive or proprietary examples are not uploaded to public or external AI services.

Agent-assisted change protocol: A task should identify scope, authoritative source files, dependent outputs, non-goals, checks to run, and evidence to report. An agent proposes reviewable changes and does not equate a successful build with content approval. AGENTS.md is a navigation and working-rules entry point, not the single master copy of project knowledge. Keep a human decision point for meaning and audience fit.

9. Acceptance, measurement, and controlled improvement

Owner-led design approval (MUST for this project’s current phase)

1. Propose: State the learning problem, a recommended solution, a simpler alternative, and what should become easier to understand.
2. Demonstrate: Supply complete chapter text, a renderable example or lightweight interactive preview, and explain changes to the reader journey.
3. Decide: The tutorial owner accepts, requests changes, or rejects; record the decision and rationale. No external learner-study gate is required.
4. Implement: The coding agent applies all approved changes to maintained sources; never substitute an AI-generated mockup for a working HTML component.
5. Verify: Check correctness, navigation, source fidelity, accessibility and responsive behavior, production build, and presentation links. Show actual output to the owner for final sign-off.

Release gates:

• Editorial: Distinct learning outcomes; concrete, reader-oriented openings; coherent paragraph and chapter transitions; limited redefinition and repetition; accurate qualifications; natural ending; benefit-led reference invitations. Owner reviews representative before/after passages.
• Learning design: Contextual questions test genuine misconceptions; labs connect action to consequence; help is available without forcing extra steps.
• Information: Stable IDs, accurate authority/revision/status claims; no fabricated agent capabilities or approvals.
• Implementation: Source validation, Astro checks/build, route/link tests, interactive tests, keyboard and mobile checks, presentation source validation, deploy verification if published.
• Presentation: Visual hierarchy and components are consistent with the site’s existing design vocabulary; the owner has seen examples before site-wide rollout.

Do not claim broad educational efficacy from owner review. Qualify it as owner-approved educational design plus technical verification. Future reader studies, analytics and Core Web Vitals may inform later iterations but are not prerequisites now.

One coordinated update may address multiple agreed improvements when their shared components/dependencies make that economical; organize as reviewable commits or change groups and deliver one integration checklist. Record: Decision ID · problem · proposed solution · owner status · rationale · affected artifacts · verification.

10. External interaction patterns: research register

These are direct reference sources for individual patterns, not templates to copy wholesale. Blog-list rankings are weak comparative evidence; official product descriptions demonstrate intended patterns but not their learning effectiveness on our audience. Adopt a pattern after a concrete demonstration and explicit owner approval; broader reader observation is optional future research.

Pattern decision log (SHOULD): reader problem → concrete proposed example → owner accept/adjust/reject → implemented component → checked result. Reader studies may be added later, but they are not a current gate. Reject interactions that merely increase decoration, content length, setup effort, or visual motion.

11. What to hand to an implementation agent

Provide the approved specification, current content and source inventory, desired change IDs, examples and test data, explicit exclusions, acceptance tests, and relevant tooling constraints. Ask the agent to inspect before editing, implement the smallest coherent vertical slice, run appropriate tests, and report verified versus unverified outcomes. Never direct it to invent screenshots, user-study findings, or a successful deployment.

Exit condition for specification approval: The reader promise, audience, groups, chapter outcomes, interactive policy, visual/UX principles, source architecture, and release criteria are agreed. Detailed component choices can be deferred until implementation.