Document-as-Code Lab — v1.3 Editorial Audit and Next Improvement Backlog

19 October 2026 · Proposal for owner approval. This is an evidence-informed editorial plan, not a claim that v1.3 or all of v1.2 has been published or tested.

1. Source baseline and confidence

• GitHub repository source currently contains 11 Markdown chapters, with Chapter 12 absent.
• Chapter 8 in the checked remote still used the earlier “AI Needs Context, Not Just Prompts” framing. The approved v1.2 agent-ready knowledge direction had not yet appeared in that source.
• The project has Astro chapter pages, quizzes, browser labs, a Contract Explorer and Architecture Explorer, and linked references. v1.2 changes must be inspected on the actual branch before rewriting their text.
• The site’s cached public search snapshot did not match the latest repository chapter list. Do not infer current deployed site behavior or visual quality from that snapshot.
• This review covers reader-facing source language and source architecture. No browser-based accessibility, performance or end-to-end interaction acceptance is claimed.

2. Editorial quality findings

Strengths to preserve: Real explanations, a coherent arc from onboarding to the functioning lab, precise boundaries between approval and validation, browser-first examples, and concise direct vocabulary.

Opportunities for smoother reading:

1. Some chapters define concepts before explaining what problem they solve (notably Chapters 2, 5, 6 and 10).
2. Repeated phrasing about “maintained information”, source/output distinction and review limits can feel more like a specification than a guided article. Keep all material qualifications, but show them at the relevant result rather than multiple generic warnings.
3. Chapter 5’s thirteen-entry “Concepts so far” table interrupts the progression into the metadata lab.
4. Chapter 9 leads with an inventory of example IDs before the reader encounters an interesting contract question.
5. Chapters 10–11 contain substantial lists of implementation details, which are valuable as references but can interrupt their architecture story.
6. Openings, takeaways and “Next” handoffs vary from natural transitions to mechanical teaching instructions.
7. Repo CONTRIBUTING.md still says each chapter should have “an exercise with an observable result”. That conflicts with the agreed optional-exercise policy and must be reconciled before an agent performs editorial work.

3. Recommended v1.3 improvement package

Delivery: One coordinated, chapter-by-chapter editorial update after current v1.2 changes are present in the branch being edited. Keep chapter diffs independent for inspection; do not ask an agent to replace all chapter files blindly. Owner sign-off is the only educational design gate at this stage; functional/accessibility verification remains required.

4. Per-chapter review map

5. Quality acceptance rubric

For every changed chapter, have an editor review seven questions, not only word count:

1. Reason to care: Does the opening provide a concrete reader question or situation?
2. Progression: Does each section make one new step toward answering it?
3. Plain accuracy: Does the text explain technical meaning clearly without equating distinct concepts?
4. No unnecessary repeat: Is each major idea defined once and revisited only for a new purpose?
5. Engagement: Is any interactive element preceded by a clear reason and followed by a useful conclusion?
6. Continuity: Is a new example introduced with its purpose, and does the ending support the next step?
7. Reference value: Can a reader tell what each deeper link offers, without being pushed into mandatory homework?

The owner decides Accept / Revise / Reject. Automated tests check links, content structures, build and component behavior but cannot certify that prose flows well. Do not optimize to a rigid sentence length, sentence count or readability score. Strong precise sentences are preferable to shorter but misleading ones.

6. Guardrails

• Preserve stable chapter IDs, front matter, maintained sources, diagrams, meaning and links unless a specific editorial change calls for updating them together.
• No accidental expansion into a Git tutorial, required coding exercises, external AI service, new front-end framework or new curriculum chapter.
• Preserve authority and lifecycle distinctions close to their relevant claims: validated ≠ approved; proposed ≠ effective; inferred candidate ≠ recorded fact; build ≠ deployment; accessible ≠ authorized.
• Do not add a quiz, image or subsection just to meet a count; the current scenarios/labs should be used more effectively.
• Do not remove an accurate nuanced point because it is harder to phrase. Move it to a supporting guide when it is optional depth.

7. Editorial delivery protocol

1. Agent inspects the latest branch and AGENTS.md, CONTRIBUTING.md, glossary, design decisions, and specification.
2. Agent prepares three sample edits (one opening, one deep explanation, one concluding chapter) with original and proposed copy, editorial rationale, and owner review status.
3. Following owner approval, apply the agreed voice and flow across all 11 chapters, preserving each one’s learning contract.
4. Update glossary, references, interactive microcopy and presentation excerpts only when their actual dependencies change.
5. Run source, link, presentation, quiz, accessibility-focused component and Astro build checks.
6. Produce a small reading-path review summary, list of changed files, unresolved questions, and evidence for checks actually run.

Not included: A user-testing study, a new information architecture application, additional dashboards, or automatic full-site rebranding.

Implementation Baseline Reconciliation

The original observations above predate the published v1.2 update. The editorial implementation starts from clean main at 6d8ee1d, with the agent-knowledge chapter, three scenario checks, guided Contract Explorer, and eleven-chapter site already deployed. The owner accepted three representative samples and authorized the editorial pass. See the accepted samples and editorial review; the original audit is retained as provenance, not a live status report.