Document-as-Code Lab — Learning Product Specification v1.3

Editorial baseline · 19 October 2026 · v1.2 functionality retained; editorial direction accepted, revised chapters in review
Derived from 01-REUSABLE-TUTORIAL-SPECIFICATION-TEMPLATE.md. Target: 11 chapters (remote repository source now confirms Chapter 12 absent); keep rewritten Chapter 10; Chapter 11’s current “Behind the Lab” treatment may be retained, selectively edited, or simplified. This is the intended specification, not a claim that everything is implemented or user-tested.

1. Product promise

Reader promise: Learn how to move from isolated documents to maintained, processable information that can be reviewed, connected, transformed, explored, and used by people, software, and AI agents.

Primary outcome: A reader can describe a credible Document-as-Code workflow and recognize how source information differs from views, approval decisions, tasks, and publication. They can inspect a working example in a browser and know where to go for a real implementation.

Secondary outcome: A practitioner can inspect the tutorial’s own GitHub/Astro implementation and adapt its patterns, or recognize analogous approaches using existing document environments such as Microsoft 365.

What it is not: A Git training course; a Markdown syntax encyclopedia; a software installation tutorial; a complete CI/CD manual; a mandate to migrate every Word document into Git; or a mandatory hands-on lab course.

Positioning: A compact, approachable learning website with purposeful visuals, self-contained browser interactions, source-linked examples, optional deeper references, and actual project evidence. The site illustrates its own subject.

2. Audiences and paths

Browser-first requirement: All chapter learning outcomes must be achievable without cloning a repository, using an AI account, or installing Node/Python. Optional implementation tasks may require tools but are outside the core path. State whether a UI example is browser-only, build-time, or actually live.

3. Curriculum structure — intended 11 chapters

Groups are coherent reader journeys. The homepage should use these semantic group definitions rather than outdated hard-coded ranges.

Chapter-by-chapter specification

Editorial decision on Chapter 11: Its current long form is not automatically rejected. Retain its valuable architectural overview; selectively tighten repeated inventories and transitions after owner review. Chapter 12’s start with one small information flow message may become a very short optional closing or a supporting reference—not another mandatory chapter.

4. Narrative examples and data boundaries

Scenario transitions: At the start of Chapter 9 say why we leave onboarding for a customer/project/contract example. At Chapter 10 say why we now examine the actual tutorial repository. Explicitly label fictional teaching datasets versus real repository status. Do not require readers to remember every example ID from earlier chapters.

5. Engagement policy

Default chapter experience: concise narrative + one concrete example + one meaningful visual or comparison + optional short quiz. Labs are selected for pedagogical value, not imposed on every chapter.

Existing core labs to preserve: Chapter 1 selection, Chapter 4 Markdown editor, Chapter 5 metadata validation, Chapter 7 processing, Chapter 9 Contract Explorer, Chapter 11 Architecture Explorer. The website already has quizzes in every chapter. Retain these unless an explicit owner decision or verified defect justifies changing them. There is no requirement to add more labs to reach an arbitrary count.

Quiz requirements: Usually 1–3 questions, each probing a common misconception or decision. Provide feedback explaining why. Avoid trivia and automatic uniform quizzes where an in-context check would work better.

Exercise requirements: No required offline exercises in core chapters. Convert procedural assignments like “clone, edit, run” into (a) optional reference activities or (b) on-page experiences when the concept benefits. Existing Try it text can be reframed as Explore if no actual local action is needed. An offsite Actions run or GitHub file is a useful inspectable example, not compulsory homework.

Components must disclose: test/fake versus real data, browser-only edits, refresh behavior, underlying maintained source, results of failed validation, and whether edits persist.

Preferred on-page learning loop

Invite → (optional predict/hint) → act → observe → explain → try another variation. Use this where learners can observe a causal change. Do not force ‘attempt first’ where a novice lacks prerequisites. Show hints and worked examples as choices, not a punishment for wrong answers. A lesson-completion statement should explain the conceptual result without pretending the source was approved or published.

Initial in-context enhancement: Chapter 5 — Validate procedure metadata. The existing editor and validator should remain the working engine. Add a small scenario question around it rather than building a second lab:

1. Invite: “What happens if a procedure has no owner?” Show owner: people-team in context and a short prediction option (or “Show me first”).
2. Act: Remove owner in the existing editor; press Validate metadata. Preserve the explicit validation action so ‘modified’ is not mistaken for ‘checked’.
3. Observe: Show a localized diagnostic (owner is required) and distinguish edited source from last validation result. Keep the editor and result simultaneously visible on desktop; use accessible order on mobile.
4. Explain: “The schema detects a missing field. It does not establish that the named owner is correct or that the procedure is approved.”
5. Recover: Restore owner, revalidate, and show a quiet “What you demonstrated” message; offer Why does this matter? to the record-processing reference.

The current lab already has an editor and explicit validation. The owner will review an integrated in-context scenario check and its explanatory feedback; technical verification covers behavior, not generalized learning claims. Avoid re-implementing the parser or changing schema rules just to fit a visual pattern.

Second guided-design target: Chapter 9 Contract Explorer. Borrow an orient → select → trace → interpret → inspect source flow from Observable and visual-storytelling sites. Make the first business question obvious (“Which delivery might be affected?”), but preserve advanced views. A graph or zoom interaction must have a readable list/table alternative.

Scenario checks: Reuse a small in-content component where a substantive judgment or misconception exists (initial targets Chapters 5, 6 and 8; additional uses only when justified). Answer feedback explains why. No scores, streaks, persistence, or obligatory completion. Retain end-of-chapter quizzes if nonduplicative, but do not force quiz counts. Optional hint/retry is encouraged.

6. References, visuals, and reader invitations

Reference discovery map

Supporting reference pages remain outside chapter numbering. Each chapter link should promise an answer/benefit and flag tools required. Provide a clear return path from supporting material.

Proposed visual system

Aesthetic: calm and modern, warm paper-like neutrals, restrained sage/olive with a small contrasting accent, human-centered lightly sketched/pencil artwork where useful, crisp technical diagrams and genuinely interactive views. This is a proposal to review, not a requirement to replace the existing visual identity.

Visual patterns to standardize: (1) annotated before/after, (2) object-relationship diagram with legend, (3) source → processing → output strip, (4) evidence/source card with status and revision, (5) quiet reference teaser, (6) lab entry/feedback block. Avoid repeating a generic four-box flowchart in every chapter.

Pacing: Keep explanatory prose next to the visual result it interprets. Use a compact top-of-section question, a focused control, and a short conclusion. Move implementation-level options to expandable details. Prefer calm persistent feedback to pop-up error interruptions. Make the graph useful without animated zoom.

Reusable graphical primitives to prototype (not all mandatory): learning-question strip; side-by-side input/result; inline hint disclosure; outcome/diagnostic bar; one-line learning reflection; source/provenance chip; and contextual next-step link. Use them only where they replace confusion or excess prose. Cards and colored labels must carry meaning, not mere visual variety.

UX behavior: Consistent headings and section spacing; table/code overflow on mobile; obvious active chapter and next/previous link; discoverable labs; concise feedback and reset; clear difference between reference links and actions; readable diagrams on narrow screens; accessible focus states and alt text. Review against WCAG 2.2 AA. Chapter text should remain useful when JavaScript is disabled.

Visual density guidance: Each chapter should have one purposeful visual explanation or interaction near the key learning moment, plus extra graphics only when they materially simplify a question. Do not mandate a decorative image on every page.

6A. v1.3 Editorial and Reading-Flow Requirements

Primary intent: Improve the reading experience without changing the learning objectives, technical meaning or approved interaction design. This is an editorial pass, not a request to expand scope or invent new content.

Voice: clear, conversational, precise and respectful. The reader is an intelligent non-specialist; practitioners may skim but should not feel talked down to. Favor people, situations and consequences over abstractions. Use exact technical words where they carry meaning, and define them at point of need.

Chapter narrative: Open with one concrete reader problem, then explain the necessary mechanism and use the existing examples/labs to demonstrate it. Don’t open each section by summarizing the previous chapter. In a natural ending, state the insight and leave a relevant next question. Avoid repeating the same benefit in the opening, last paragraph and boxed takeaway.

Specific continuity requirements: Use the Onboarding Lab consistently in Chapters 1–7; move from that example to the actual repository and agent-ready knowledge in Chapter 8; explicitly introduce the fictional contracts scenario in Chapter 9; close by revealing the real build/publishing architecture in Chapters 10–11. Transitions should explain why the reader is seeing a different example.

Caveats: Keep important distinctions—metadata validity versus accuracy/approval; requirement approval versus implementation; review candidate versus confirmed impact; source versus generated view; build-time versus live; agent file access versus authority. Place each qualification next to the particular example or result where confusion could arise, and eliminate repetitive generic warnings elsewhere.

Lists, tables, callouts: Keep only those that improve scanning or comparison. Replace long definitions tables inside core chapters with a small relevant comparison and a glossary invitation. A scenario question should flow naturally from surrounding text, not feel like an isolated exam. A reference card should offer useful depth without interrupting the main story.

Editor quality gates:

• Chapter starts with a specific question/situation within the opening ~100 words.
• Every section advances the single intended chapter insight; repeated definitions are consolidated or linked.
• New technical terms are explained at first useful appearance, not preloaded in bulk.
• Headings and transitions create a readable progression; avoid formulaic “This chapter…” and “Next…” boilerplate when prose works better.
• Questions, diagrams and labs are introduced and followed by a sentence explaining the consequence.
• Source links and optional references promise a concrete benefit, and any prerequisites are explicit.
• Meaning of the original claims is preserved; no changed technical assertions without source verification.
• The owner reviews representative before/after passages before approving a site-wide editorial pattern.

No mandatory word quota and no mandatory exercise per chapter. Retain concise writing but do not amputate the example, rationale or necessary qualification to reach a number.

Chapter-by-chapter editorial opportunities

7. Implementation architecture (the tutorial, not the universal standard)

Transferability: Describe equivalent capabilities, not false one-to-one tool equivalence. OneDrive/SharePoint offer managed files and versions; Copilot/agent integrations can retrieve files and, with appropriately configured tools and permissions, modify them; review and automation may be implemented through SharePoint/Power Automate. They do not become Git pull requests by being in the cloud.

8. v1.2 functional acceptance and v1.3 editorial criteria

The tutorial has 11 chapters as the desired finished state. The public repository currently lists 11 chapter sources, with Chapter 12 absent. Confirm that navigation, decks, reference links and a production build reflect the same 11-chapter structure.

1. Eleven-chapter integrity: No obsolete Chapter 12 page, navigation, final next-link, slides or source refs; route redirects checked; all book/README references reconciled.
2. Chapter 8: Explains agent-ready knowledge and the distinct roles of AGENTS.md, project information architecture, conventions, decisions, maintained sources, and validation; one short, useful scenario check; references updated to remove the obvious with/without-context exercise from the default path.
3. In-context checks: A single reusable Astro component with a structured question source, accessible radio inputs, Check answer, meaningful feedback, optional hint, retry/reset and static fallback; initial approved questions in Ch 5, Ch 6 and Ch 8. No score or forced progression.
4. Guided Chapter 9: An inviting first business question above the existing Contract Explorer; direct versus derived connections and proposed status remain accurate. Do not replace the underlying source-based model or make new persisted state.
5. Visual consistency: Reuse the current homepage olive/sage, ochre and violet accents, neutral backgrounds, spacing and typography. A small set of calm learning, evidence and supporting-link components; accessible on desktop/mobile. Do not introduce a new JS framework.
6. Better reference links: At least one value-led reference entry at a natural point in each relevant chapter, with prerequisite/no-setup context when useful. References stay separate from numbered chapters.
7. Knowledge architecture: AGENTS.md links to maintained guidance rather than duplicating it. If an architecture map/decision log does not exist, add only a lean, accurate version grounded in real repo structure and agreed decisions. Prefer existing GLOSSARY.md, CONTRIBUTING.md, tests and schemas where adequate.
8. Experience and reliability: Visual review by the owner; correct browser states and source citations; no account or local tools for core path; keyboard/no-JS/mobile behavior checked; all Astro check/build, tests, slides and links pass; deployment verified only after publication.

v1.3 editorial release acceptance: Representative before/after passages demonstrate smoother entry, reduced unnecessary repetition, consistent terminology and a stronger narrative bridge for each changed chapter; interaction meaning and source fidelity are unchanged. CONTRIBUTING.md, AGENTS.md and any editorial guide use consistent optional-exercise and style rules. Avoid overwriting v1.2 component work when it lands.

Evaluation model: owner reviews concrete examples and implementation. External reader studies and learner-success statistics are not release gates and must not be claimed. This is an owner-approved design and technically checked learning product.

9. Controlled development after v1

v1.2 work package — one coordinated agent update, seven workstreams:

1. Update and keep this specification, the reusable template and audit synchronized with approved decisions.
2. Rewrite Chapter 8 and reframe its long reference around project knowledge, AGENTS.md, architecture, language, decisions, source authority and checks.
3. Implement reusable in-context scenario checks, initially Ch 5/6/8, with rationale-based feedback and accessibility.
4. Give Chapter 9 a guided entry into its existing Contract Explorer, without rebuilding the graph or changing source data.
5. Apply a restrained chapter-level visual system based on existing site styling.
6. Give supporting references contextual, benefit-oriented entry points.
7. Finish the 11-chapter cleanup across site, content registry, quiz sources, presentation YAML, links and README.

Delivery approach: The seven items belong to one integrated review/update, but the agent must keep them separable in the diff, preserve existing work, and report verification by workstream. No commit or push without explicit authorization. Technical correctness is checked by CI/local build; content/design approval remains with the owner.

Design decisions: See the decision register and accepted editorial samples. Details of typography and spacing may be refined in owner review, but default to the current site palette and avoid rebranding.

v1.3 Editorial Quality

One integrated editorial pass across all 11 chapters and their immediately linked reference invitations. Start from the actual repository after v1.2 is merged; do not blindly overwrite changed chapter text with an old proposed file. Group changes chapter by chapter so the owner can review each diff. Update writing guidance in CONTRIBUTING.md and reference it from AGENTS.md, rather than hiding the conventions in this specification alone. Include at least three representative before/after examples before requesting owner approval for the editing pattern. Do not launch a second framework or new full-size lab.

Prioritize: (a) introduction/flow/terminology, (b) repetition and depth boundaries, (c) bridges between examples and chapters, (d) lab/quiz microcopy, (e) contextual reference-link language, and (f) final editorial and technical verification.

10. Targeted reference-pattern decisions for v1.2

Research provenance: Brilliant/Khan/Code.org/Observable/Google Arts & Culture/The Pudding provide interaction inspiration, not measured comparative learning proof. Accessibility reference: W3C/WAI; test actual behavior before claiming WCAG conformance.

11. Evidence reviewed and limits

Source baseline inspected on 19 October 2026: repository, chapters, Astro site, decks, workflows. Ch 10 and Ch 11 rewrites and the Architecture Explorer are on the remote branch. The remote repository now lists 11 chapter files, with Chapter 12 absent. That package inspection preceded the verified v1.2 release. Implementation starts from clean main at 6d8ee1d, where the agent-knowledge rewrite, three scenario checks, guided Contract Explorer, and eleven-chapter site are published. Preserve those implementations.

The v1.2 implementation record describes its local and hosted functional checks. This editorial revision needs its own regression evidence; neither a full accessibility/performance audit nor wider learning effectiveness is established by the sample approval. The editorial review records the changed reading path and actual checks.