K
K12worX Education501(c)(3) Public Charity
Jamboree

Learning Guide Generation Documentation

Created: December 2025 Purpose: Document how the K12worX Learning Guide was created and how to maintain/enhance it

Overview

The K12worX Learning Guide is a comprehensive, 10-chapter educational resource designed to take students from complete beginners to confident contributors to our Next.js website. It was generated collaboratively between human developers and Claude Code AI assistant over multiple sessions in December 2025.

Total Content Generated:

  • 10 chapters (Chapters 0-10)
  • 55 individual markdown files
  • ~500KB of educational content
  • 72 static pages in production build

Access the guide: /website/docs/learning-guide/README.md

Generation Process

Phase 1: Foundation (Chapters 0-4)

Objective: Establish prerequisites and foundational understanding

Chapters created:

  1. Chapter 0: Prerequisites - Development environment setup
  2. Chapter 1: Understanding Basics - Core web development concepts
  3. Chapter 2: Getting Started - Hands-on with the codebase
  4. Chapter 3: Understanding Structure - Next.js App Router architecture
  5. Chapter 4: Reading Code - Code literacy through real examples

Approach:

  • Created comprehensive README outlines first
  • Generated content files based on actual K12worX codebase
  • Used real code examples from production files
  • Included hands-on exercises students can complete
  • Built progressive learning path

Key Decision: Use actual codebase files rather than generic examples to ensure relevance and accuracy.

Phase 2: Practical Skills (Chapters 5-7)

Objective: Build practical skills for contributing

Chapters created:

  1. Chapter 5: Styling Basics - Tailwind CSS mastery
  2. Chapter 6: Making Changes - Safe, incremental modifications
  3. Chapter 7: Git Basics - Version control workflow

Approach:

  • Extracted patterns from actual tailwind.config.ts
  • Created exercises based on real homepage components
  • Documented our team's Git workflow
  • Provided troubleshooting for common mistakes

Key Decision: Focus on our specific tech stack and patterns rather than comprehensive web dev education.

Phase 3: Advanced Topics (Chapter 8)

Objective: Enable students to build new features independently

Chapter created:

  • Chapter 8: Advanced Topics - Pages, components, forms, TypeScript

Approach:

  • Show how to create new pages using App Router
  • Component architecture with TypeScript interfaces
  • Form handling with state management
  • Type safety patterns

Key Decision: Balance between teaching fundamentals and K12worX-specific patterns.

Phase 4: Self-Sufficiency (Chapters 9-10)

Objective: Make students independent problem-solvers

Chapters created:

  1. Chapter 9: Troubleshooting - Error resolution and debugging
  2. Chapter 10: Reference - Quick reference materials

Approach:

  • Catalogued common errors from actual development
  • Documented debugging workflows using browser DevTools
  • Created comprehensive glossary of technical terms
  • Compiled command reference from daily workflows
  • Curated external learning resources
  • Mapped complete codebase structure

Key Decision: Teach problem-solving and resource discovery, not just solutions.

Content Structure Pattern

Each chapter follows this consistent structure:

Chapter README

# Chapter Title

## What You'll Learn
- Learning objectives (3-5 bullet points)

## Chapter Contents
- List of lessons with descriptions

## Prerequisites
- What students should complete first

## Time Estimate
- Realistic time commitment

## Quick Navigation
- Links to lessons

Individual Lesson Files

# Lesson Title

[Introduction paragraph explaining what and why]

## What You'll Learn
- Specific learning objectives

## [Main Content Sections]
- Concept explanations
- Code examples (from real codebase)
- Visual aids (code blocks, structure diagrams)

## Hands-on Exercise
- Practical task students can complete

## Common Patterns / Key Concepts
- Summary of important patterns

## Troubleshooting
- Common mistakes and solutions

## Quick Reference
- Cheat sheet format summary

## What's Next
- Link to next lesson

## Quick Links
- Navigation breadcrumbs

Design Principles:

  1. Progressive complexity - Each lesson builds on previous
  2. Real examples - Use actual K12worX code, not generic samples
  3. Active learning - Hands-on exercises in every lesson
  4. Safety net - Troubleshooting and common errors addressed
  5. Interconnected - Cross-references between related topics
  6. Scannable - Headers, code blocks, lists for easy reference

Technology Decisions

Why Markdown?

  • Version control friendly - Diffs work well in Git
  • Portable - Works with any text editor
  • Simple - Students can contribute improvements
  • Flexible - Can migrate to MDX later if needed

Why Not MDX Initially?

  • Simpler to generate and maintain
  • Fewer dependencies
  • Students can edit without React knowledge
  • Can always migrate later with search/replace

Rendering Solution

Used react-markdown with plugins:

  • remark-gfm - GitHub Flavored Markdown (tables, task lists)
  • rehype-highlight - Syntax highlighting
  • rehype-slug - Auto-generate heading IDs for anchor links

Why this stack:

  • Works with static export (output: 'export')
  • No build-time compilation needed
  • Lightweight and performant
  • Good syntax highlighting out of box

File Organization

website/docs/learning-guide/
├── README.md                          # Guide overview and navigation
│
├── 00-prerequisites/                  # Chapter 0
│   ├── README.md                      # Chapter overview
│   ├── required-software.md
│   ├── creating-github-account.md
│   ├── installing-vscode.md
│   ├── installing-nodejs.md
│   ├── installing-git.md
│   ├── command-line-basics.md
│   └── joining-the-team.md
│
├── 01-understanding-basics/           # Chapter 1
│   ├── README.md
│   ├── what-is-code.md
│   ├── files-and-folders.md
│   ├── html-basics.md
│   ├── css-basics.md
│   ├── javascript-basics.md
│   └── how-websites-work.md
│
├── 02-getting-started/                # Chapter 2
│   ├── README.md
│   ├── cloning-the-repo.md
│   ├── opening-in-vscode.md
│   ├── installing-dependencies.md
│   ├── running-dev-server.md
│   └── your-first-change.md
│
├── [03-10]/                           # Remaining chapters
│   └── [Similar structure]
│
└── learning-guide-generation.md       # This file

Naming conventions:

  • Folders: ##-chapter-name/ (numbered for order)
  • Files: kebab-case.md (descriptive, SEO-friendly)
  • READMEs: Capital README.md (GitHub convention)

Content Quality Standards

Writing Style

  • Tone: Friendly, encouraging, non-condescending
  • Voice: Second person ("you"), active voice
  • Clarity: Short sentences, simple words, clear explanations
  • Examples: Always from real K12worX codebase
  • Encouragement: Normalize mistakes and learning process

Code Examples

// ❌ Bad - show what NOT to do
const broken = undefined.property;

// ✅ Good - show the right way
const safe = data?.property;

Format:

  • Syntax highlighting for all code blocks
  • Language specified (tsx, bash, json, etc.)
  • Comments explaining non-obvious parts
  • Show both wrong and right approaches

Technical Accuracy

  • Test all commands before documenting
  • Verify file paths exist in codebase
  • Check line numbers for code references
  • Update with codebase changes when structure changes

Maintenance Guidelines

When to Update

Must update when:

  • Dependencies change (Next.js, React versions)
  • File structure changes (routes, components move)
  • New patterns adopted (different state management, etc.)
  • Errors found in examples

Should update when:

  • Better examples become available
  • Common student questions arise
  • New tools/techniques emerge
  • External resources change

Can update when:

  • Writing style can be improved
  • Additional exercises would help
  • More troubleshooting tips identified

How to Update

  1. Identify what changed in codebase
  2. Find affected lessons (use grep for file paths)
  3. Update examples to match current code
  4. Test the changes work as documented
  5. Update cross-references if lesson structure changes
  6. Verify build still passes
  7. Update this document with significant changes

Version Control

Track changes:

  • Update "Last Updated" dates in chapter READMEs
  • Document breaking changes in this file
  • Use descriptive commit messages
  • Reference issues/PRs that prompted updates

Enhancement Ideas

Near-term Improvements

Add interactive elements:

  • Quizzes at end of chapters
  • Code sandboxes for practice
  • Progress tracking (checkboxes)

Expand content:

  • Video walkthroughs for complex topics
  • Downloadable cheat sheets (PDF)
  • Sample projects to build

Better navigation:

  • Search functionality
  • Table of contents on every page
  • Progress indicator

Long-term Enhancements

Community features:

  • Student-contributed tips sections
  • FAQ from real questions
  • "Common mistakes" from actual errors

Personalization:

  • Different learning paths (visual vs. text)
  • Skip-ahead for experienced students
  • Deep-dive sections for advanced learners

Assessment:

  • Knowledge checks between chapters
  • Practical project requirements
  • Code review exercises

Migration to MDX:

  • Interactive code examples
  • Live preview of changes
  • Embedded exercises

AI-Assisted Generation Process

What Worked Well

Context-aware generation:

  • Reading actual codebase files before writing
  • Using real component examples
  • Matching existing documentation style
  • Following established patterns

Iterative refinement:

  • Chapter outlines first, then content
  • Build verification after each chapter
  • Consistent structure across all lessons
  • Progressive difficulty tuning

Quality controls:

  • Cross-referencing related topics
  • Including troubleshooting in every lesson
  • Real-world examples over theoretical ones
  • Testing all commands before documenting

Challenges and Solutions

Challenge: Keeping content synchronized with codebase Solution: Reference specific files/lines, use grep patterns

Challenge: Balancing depth vs. accessibility Solution: Quick start + detailed explanations + external links

Challenge: Maintaining consistent tone across 55 files Solution: Established style guide, used templates

Challenge: Avoiding tutorial hell Solution: Hands-on exercises, real contributions encouraged early

Lessons Learned

Content Creation

  1. Start with structure - READMEs and outlines before content
  2. Use real examples - Generic tutorials don't transfer well
  3. Progressive complexity - Don't jump difficulty levels
  4. Test everything - Every command, every path, every example
  5. Cross-reference liberally - Help students make connections

Technical Approach

  1. Simple is better - Markdown over MDX initially
  2. Static generation - Pre-render all pages for performance
  3. Navigation is crucial - Breadcrumbs, prev/next, TOC
  4. Mobile-first - Many students on phones/tablets
  5. Offline-friendly - All content in repo, no external dependencies

Pedagogical Insights

  1. Normalize failure - Debugging is learning
  2. Multiple formats - Text, code, exercises, references
  3. Just-in-time learning - Teach concepts when needed
  4. Build confidence early - First change in Chapter 2
  5. Independence is the goal - Teach problem-solving, not answers

Replicating This Process

For Other Projects

To create a similar learning guide:

  1. Analyze your codebase

    • What's the tech stack?
    • What are common patterns?
    • Where do beginners get stuck?

  2. Define your audience

    • Prior knowledge assumptions?
    • End goal (contributor, user, maintainer)?
    • Time they can commit?

  3. Outline the journey

    • Map prerequisites
    • Identify knowledge milestones
    • Create progressive path
    • Plan 8-12 chapters

  4. Generate content systematically

    • Chapter outlines first
    • One chapter at a time
    • Use real codebase examples
    • Build/test after each chapter

  5. Iterate based on feedback

    • Watch where students struggle
    • Update confusing sections
    • Add FAQs from real questions
    • Improve based on usage

AI Collaboration Tips

To work effectively with AI assistants:

  1. Provide context - Share relevant files, explain goals
  2. Be specific - "Generate Chapter 5 about Tailwind" not "make docs"
  3. Review critically - AI makes mistakes, verify examples
  4. Iterate - First draft → feedback → refinement
  5. Maintain consistency - Use templates, style guides
  6. Test everything - AI can hallucinate file paths, commands

Metrics for Success

Quantitative

  • Completion rate - % of students finishing guide
  • Time to first contribution - Days from start to first PR
  • Error rate - Issues opened about guide problems
  • Usage analytics - Most/least visited pages

Qualitative

  • Student confidence - Self-reported before/after
  • Code review quality - Fewer basic mistakes in PRs
  • Question types - Shift from "how" to "why" questions
  • Contributions - Students improving the guide itself

Feedback Collection

Methods:

  • End-of-chapter surveys
  • GitHub issues for suggestions
  • Team retros on onboarding
  • Student interviews after completion

Questions to ask:

  • What was confusing?
  • What was most helpful?
  • What's missing?
  • What could be removed?
  • How long did it actually take?

Resources

Internal References

External Resources Used

Tools Used

  • Content Generation: Claude Code (Anthropic)
  • Markdown Rendering: react-markdown + rehype/remark plugins
  • Syntax Highlighting: rehype-highlight
  • Build Verification: Next.js build process

Changelog

December 2025 - Initial Creation

Chapters 0-4: Foundation and basics Chapters 5-7: Practical skills Chapter 8: Advanced topics Chapters 9-10: Self-sufficiency and reference

Total: 55 markdown files, 72 generated pages

Contact

Questions about the learning guide or this documentation?

  • GitHub Issues: Report errors or suggest improvements
  • Team Discussion: Discuss major changes or enhancements
  • Direct Contribution: Submit PRs to improve content

License

This learning guide is part of the K12worX Learning Jamboree project and is licensed under ISC.

Last Updated: December 11, 2025 Next Review: March 2026 or when major codebase changes occur